Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

19.8 KB
Raw Blame
"use client";

import { useEffect, useMemo, useRef, useState } from "react";
import {
  BookOpenText,
  Loader2,
  PencilLine,
  Sparkles,
  Square,
  Star,
  Volume2,
  X,
} from "lucide-react";
import { useTranslation } from "react-i18next";
import { fetchAuthStatus } from "@/lib/auth";
import { randomUuid } from "@/lib/random-uuid";
import { getOwnLearnerProfile } from "@/lib/profile-api";
import {
  primaryReadingActionRank,
  readingActionClass,
  resolveReadingAgeMode,
  type ReadingAgeMode,
} from "@/lib/reading-age-presentation";
import {
  listReadingExtensions,
  runReadingExtension,
  submitReadingQuizAnswers,
  type ReadingExtensionManifest,
  type ReadingExtensionResult,
  type ReadingQuizReward,
} from "@/lib/reading-api";
import { useReadingActions } from "./reading-actions-context";
import { useReadAloudSpeech } from "./use-read-aloud-speech";
import Tooltip from "@/shared/ui/Tooltip";

type VocabularyTerm = {
  term: string;
  meaning: string;
  usage: string;
};

type QuizQuestion = {
  id?: string;
  prompt: string;
  choices: string[];
  correct_choice_index?: number;
};

type TranslationResult = {
  translation: string;
  alternatives: string[];
  note: string;
};

const PRIMARY_ACTION_ICONS = [Volume2, BookOpenText, PencilLine] as const;

type ReadingExtensionBarProps = {
  materialId: string;
  locator: number;
  /**
   * The unit the selection was made in, when there is one.
   *
   * `locator` is the *viewport* locator and drifts as the reader scrolls. The
   * server verifies the quote against the text of the unit it is told about
   * and 400s when they disagree, so a selection has to travel with its own.
   */
  selectionLocator?: number;
  selection?: string;
  sessionId?: string | null;
  onError: (message: string) => void;
};

/**
 * The strip of action buttons above the page.
 *
 * Inside a reading workspace an adult reader does not get it: the same
 * actions live where they are needed — on the selection popover, in the
 * companion's tools menu and on the header's read-aloud button — and their
 * results land in the companion column. A strip of chips that were greyed
 * out until something was selected, with a result slot of its own between
 * the toolbar and the page, was a third place to look. Younger learners keep
 * it: three big coloured buttons are the whole point of their layout.
 */
export function ReadingExtensionBar(props: ReadingExtensionBarProps) {
  const shared = useReadingActions();
  if (shared && shared.ageMode === "default") return null;
  return <ExtensionToolbar {...props} />;
}

function ExtensionToolbar({
  materialId,
  locator,
  selectionLocator,
  selection,
  sessionId,
  onError,
}: ReadingExtensionBarProps) {
  const { i18n, t } = useTranslation();
  const [extensions, setExtensions] = useState<ReadingExtensionManifest[]>([]);
  const [busy, setBusy] = useState("");
  const [result, setResult] = useState<ReadingExtensionResult | null>(null);
  const [resultLocator, setResultLocator] = useState(locator);
  const [ageMode, setAgeMode] = useState<ReadingAgeMode>("default");
  const { speak, speaking, stop: stopSpeaking } = useReadAloudSpeech();

  useEffect(() => {
    let active = true;
    void listReadingExtensions()
      .then((rows) => {
        if (active) setExtensions(rows);
      })
      .catch((error) => {
        if (active) onError(error instanceof Error ? error.message : String(error));
      });
    return () => {
      active = false;
    };
  }, [onError]);

  useEffect(() => {
    let active = true;
    void fetchAuthStatus().then(async (status) => {
      const learnerMode = status?.preset === "learner" || Boolean(status?.learning_policy);
      if (!learnerMode) {
        if (active) setAgeMode("default");
        return;
      }
      const profile = await getOwnLearnerProfile().catch(() => null);
      if (active) {
        setAgeMode(
          resolveReadingAgeMode({
            learnerMode,
            profileAge: profile?.age,
            policyAgeBand: status?.learning_policy?.age_band,
          }),
        );
      }
    });
    return () => {
      active = false;
    };
  }, []);

  // Two effects, because the two things they clean up move on different
  // clocks. A result belongs to the document: keyed on `locator` as well, an
  // ordinary scroll erased a card the reader was still reading, since
  // `locator` is the scroll-derived *viewport* locator.
  useEffect(() => {
    setResult(null);
  }, [materialId]);

  // Speech, on the other hand, must stop the moment the reader navigates
  // away from the passage being read aloud — so this one keeps both keys.
  useEffect(() => stopSpeaking, [locator, materialId, stopSpeaking]);

  const actions = useMemo(
    () =>
      extensions
        .flatMap((extension) => extension.actions.map((action) => ({ extension, action })))
        .sort((left, right) => {
          const leftRank = primaryReadingActionRank(`${left.extension.id}:${left.action.id}`);
          const rightRank = primaryReadingActionRank(`${right.extension.id}:${right.action.id}`);
          return (leftRank < 0 ? 3 : leftRank) - (rightRank < 0 ? 3 : rightRank);
        }),
    [extensions],
  );

  async function run(
    extension: ReadingExtensionManifest,
    action: ReadingExtensionManifest["actions"][number],
  ) {
    const key = `${extension.id}:${action.id}`;
    const requestedLocator = selection?.trim() ? (selectionLocator ?? locator) : locator;
    setBusy(key);
    try {
      const next = await runReadingExtension(materialId, extension.id, action.id, {
        locator: requestedLocator,
        selection: selection || "",
        locale: i18n.language,
      });
      setResult(next);
      setResultLocator(requestedLocator);
      if (next.type === "browser_speech") {
        const text = String(next.payload.text || "");
        const played = await speak({
          materialId,
          locator: requestedLocator,
          locale: String(next.payload.locale || i18n.language),
          fallbackText: text,
        });
        if (!played) {
          onError(t("No speech voice is available in this browser."));
        }
      }
    } catch (error) {
      onError(error instanceof Error ? error.message : String(error));
    } finally {
      setBusy("");
    }
  }

  if (actions.length === 0) return null;
  return (
    <>
      <div
        data-reading-presentation={ageMode}
        className="dt-reading-extensions flex shrink-0 gap-1.5 overflow-x-auto border-b border-[var(--border)] bg-[color-mix(in_srgb,var(--muted)_25%,transparent)] px-2.5 py-2"
      >
        {actions.map(({ extension, action }) => {
          const key = `${extension.id}:${action.id}`;
          const needsSelection = action.requires.includes("selection") && !selection?.trim();
          // `busy === key`, not `Boolean(busy)`: an action can take the full
          // server timeout, and disabling all six meanwhile is
          // indistinguishable from the toolbar being broken.
          const disabled = busy === key || needsSelection;
          const builtInLabel = builtInActionLabel(extension.id, action.id);
          const primaryRank = primaryReadingActionRank(key);
          const shortLabel =
            ageMode === "early"
              ? primaryRank === 0
                ? "Listen"
                : primaryRank === 1
                  ? "Look up word"
                  : primaryRank === 2
                    ? "Quiz"
                    : null
              : null;
          const Icon =
            (ageMode !== "default" ? PRIMARY_ACTION_ICONS[primaryRank] : null) ?? Sparkles;
          const iconSize = primaryRank >= 0 && ageMode === "early" ? 18 : 14;
          const button = (
            <button
              key={key}
              type="button"
              disabled={disabled}
              aria-label={
                shortLabel && builtInLabel
                  ? `${t(shortLabel)} — ${t(builtInLabel)}`
                  : undefined
              }
              onClick={() => void run(extension, action)}
              className={readingActionClass(ageMode, key)}
            >
              {busy === key ? (
                <Loader2 size={iconSize} className="animate-spin" />
              ) : (
                <Icon size={iconSize} aria-hidden="true" />
              )}
              <span
                className={
                  primaryRank >= 0 && ageMode !== "default"
                    ? "min-w-0 text-center max-sm:break-words sm:whitespace-nowrap"
                    : "truncate text-center"
                }
              >
                {shortLabel ? t(shortLabel) : builtInLabel ? t(builtInLabel) : action.label}
              </span>
            </button>
          );
          if (!needsSelection) return button;
          return (
            <span
              key={key}
              className={
                ageMode === "default"
                  ? "inline-flex min-w-[88px] flex-1 [&>span]:w-full [&>span>button]:w-full"
                  : "inline-flex w-max flex-none max-sm:min-w-0 max-sm:w-0 max-sm:flex-1 [&>span]:w-full [&>span>button]:w-full"
              }
            >
              <Tooltip label={t("Select text in the document first.")}>
                {button}
              </Tooltip>
            </span>
          );
        })}
      </div>
      {speaking ? (
        <div
          role="status"
          className="mx-3 mb-2 flex shrink-0 items-center gap-2 rounded-xl bg-[var(--card)] px-3 py-2 text-xs text-[var(--muted-foreground)] shadow-[var(--dt-shadow-xs,0_0_0_1px_rgba(0,0,0,.06))]"
        >
          <Volume2 size={14} />
          <span>{t("Reading aloud")}</span>
          <span className="ml-auto">
            <Tooltip label={t("Stop reading aloud")}>
              <button
                type="button"
                aria-label={t("Stop reading aloud")}
                onClick={stopSpeaking}
                className="inline-flex h-7 w-7 items-center justify-center rounded-md text-[var(--foreground)] transition hover:bg-[var(--muted)]"
              >
                <Square size={12} fill="currentColor" />
              </button>
            </Tooltip>
          </span>
        </div>
      ) : null}
      {result && result.type !== "browser_speech" ? (
        <ExtensionResult
          result={result}
          materialId={materialId}
          locator={resultLocator}
          sessionId={sessionId}
          closeLabel={t("Close")}
          onClose={() => setResult(null)}
          onError={onError}
        />
      ) : null}
    </>
  );
}

export function builtInActionLabel(extensionId: string, actionId: string) {
  if (extensionId === "read_aloud" && actionId === "read") {
    return "Read aloud";
  }
  if (extensionId === "guided_learning" && actionId === "guide") {
    return "Guide me";
  }
  if (extensionId === "vocabulary" && actionId === "explain") {
    return "Explain vocabulary";
  }
  if (extensionId === "quiz" && actionId === "start") {
    return "Quiz me";
  }
  if (extensionId === "translation" && actionId === "translate_en") {
    return "Translate to English";
  }
  if (extensionId === "translation" && actionId === "translate_zh") {
    return "Translate to Chinese";
  }
  return "";
}

export function ExtensionResult({
  result,
  materialId,
  locator,
  sessionId,
  closeLabel,
  onClose,
  onError,
  variant = "strip",
}: {
  result: ReadingExtensionResult;
  materialId: string;
  locator: number;
  sessionId?: string | null;
  closeLabel: string;
  onClose: () => void;
  onError: (message: string) => void;
  /**
   * `strip` is the band under the toolbar, with its own title and close
   * button. `card` is the body of a companion card, whose header already
   * carries both.
   */
  variant?: "strip" | "card";
}) {
  const questions = Array.isArray(result.payload.questions)
    ? (result.payload.questions as QuizQuestion[])
    : [];
  const items = Array.isArray(result.payload.items) ? result.payload.items.map(String) : [];
  const steps = Array.isArray(result.payload.steps) ? result.payload.steps.map(String) : [];
  const terms: VocabularyTerm[] = Array.isArray(result.payload.terms)
    ? result.payload.terms
        .map((row) => {
          if (typeof row !== "object" || row === null) return null;
          const term = row as Partial<VocabularyTerm>;
          return {
            term: String(term.term || ""),
            meaning: String(term.meaning || ""),
            usage: String(term.usage || ""),
          };
        })
        .filter((row): row is VocabularyTerm => row !== null)
    : [];
  const translation: TranslationResult = {
    translation: String(result.payload.translation || ""),
    alternatives: Array.isArray(result.payload.alternatives)
      ? result.payload.alternatives.map(String)
      : [],
    note: String(result.payload.note || ""),
  };
  const body = String(result.payload.body || result.payload.overview || "");
  const card = variant === "card";
  return (
    <section
      className={
        card
          ? "text-[12.5px] leading-relaxed text-[var(--foreground)] [&>*:first-child]:mt-0"
          : "relative mx-3 mb-2 shrink-0 rounded-xl bg-[var(--card)] px-3 py-3 text-xs text-[var(--foreground)] shadow-[var(--dt-shadow-xs,0_0_0_1px_rgba(0,0,0,.06))]"
      }
    >
      {card ? null : (
        <>
          <button
            type="button"
            onClick={onClose}
            aria-label={closeLabel}
            className="absolute right-2 top-2 text-[var(--muted-foreground)]"
          >
            <X size={14} />
          </button>
          <h3 className="pr-6 font-semibold">{result.title}</h3>
        </>
      )}
      {result.message ? (
        <p className="mt-1 text-[var(--muted-foreground)]">{result.message}</p>
      ) : null}
      {body ? <p className="mt-2 whitespace-pre-wrap">{body}</p> : null}
      {translation.translation ? (
        <p className="mt-2 whitespace-pre-wrap font-medium">{translation.translation}</p>
      ) : null}
      {translation.note ? (
        <p className="mt-1 text-[var(--muted-foreground)]">{translation.note}</p>
      ) : null}
      {translation.alternatives.length ? (
        <ul className="mt-2 list-disc space-y-1 pl-5 text-[var(--muted-foreground)]">
          {translation.alternatives.map((alternative, index) => (
            <li key={`${index}-${alternative}`}>{alternative}</li>
          ))}
        </ul>
      ) : null}
      {items.length ? (
        <ul className="mt-2 list-disc space-y-1 pl-5">
          {items.map((item, index) => (
            <li key={`${index}-${item}`}>{item}</li>
          ))}
        </ul>
      ) : null}
      {steps.length ? (
        <ol className="mt-2 list-decimal space-y-1 pl-5">
          {steps.map((step, index) => (
            <li key={`${index}-${step}`}>{step}</li>
          ))}
        </ol>
      ) : null}
      {terms.length ? (
        <dl className="mt-2 space-y-2">
          {terms.map((term, index) => (
            <div
              key={`${index}-${term.term}`}
              className="pt-2.5 first:pt-0"
            >
              <dt className="font-medium">{term.term}</dt>
              <dd className="mt-1 text-[var(--muted-foreground)]">{term.meaning}</dd>
              <dd className="mt-1 text-[var(--muted-foreground)]">{term.usage}</dd>
            </div>
          ))}
        </dl>
      ) : null}
      {questions.length ? (
        <QuizQuestions
          questions={questions}
          materialId={materialId}
          locator={locator}
          sessionId={sessionId}
          onError={onError}
        />
      ) : null}
    </section>
  );
}

function QuizQuestions({
  questions,
  materialId,
  locator,
  sessionId,
  onError,
}: {
  questions: QuizQuestion[];
  materialId: string;
  locator: number;
  sessionId?: string | null;
  onError: (message: string) => void;
}) {
  const { t } = useTranslation();
  const [answers, setAnswers] = useState<Record<string, number>>({});
  const [verdicts, setVerdicts] = useState<Record<string, boolean>>({});
  const [reward, setReward] = useState<ReadingQuizReward | null>(null);
  const [saving, setSaving] = useState<Record<string, boolean>>({});
  const pendingSubmissions = useRef<Record<string, { selected: number; id: string }>>({});

  async function persistAnswer(question: QuizQuestion, index: number, choiceIndex: number) {
    const questionId = question.id || `q_${index + 1}`;
    const key = question.id || String(index);
    const pending = pendingSubmissions.current[key];
    const submissionId = pending?.selected === choiceIndex ? pending.id : randomUuid();
    pendingSubmissions.current[key] = { selected: choiceIndex, id: submissionId };
    setSaving((current) => ({ ...current, [key]: true }));
    try {
      const results = await submitReadingQuizAnswers(materialId, {
        locator,
        session_id: sessionId || "",
        submission_id: submissionId,
        answers: [{ question_id: questionId, selected_index: choiceIndex }],
      });
      const verdict = results.answers.find((item) => item.question_id === questionId);
      if (!verdict) throw new Error(t("Failed to save answer. Please try again."));
      setAnswers((current) => ({ ...current, [key]: choiceIndex }));
      setVerdicts((current) => ({ ...current, [key]: verdict.is_correct }));
      setReward(results.reward ?? null);
      delete pendingSubmissions.current[key];
    } catch (error) {
      onError(error instanceof Error ? error.message : String(error));
    } finally {
      setSaving((current) => ({ ...current, [key]: false }));
    }
  }

  return (
    <>
      {questions.map((question, index) => {
        const key = question.id || String(index);
        const selected = answers[key];
        const correctChoiceIndex = Number.isInteger(question.correct_choice_index)
          ? Number(question.correct_choice_index)
          : -1;
        const canGrade = correctChoiceIndex >= 0 && correctChoiceIndex < question.choices.length;
        if (!canGrade) {
          return (
            <div key={key} className="mt-3">
              <p className="font-medium">{question.prompt}</p>
              <ol className="mt-1 list-inside list-[upper-alpha] space-y-0.5 text-[var(--muted-foreground)]">
                {question.choices.map((choice) => (
                  <li key={choice}>{choice}</li>
                ))}
              </ol>
            </div>
          );
        }
        return (
          <fieldset key={key} className="mt-3">
            <legend className="font-medium">{question.prompt}</legend>
            <div className="mt-1 grid gap-1">
              {question.choices.map((choice, choiceIndex) => (
                <button
                  key={choice}
                  type="button"
                  aria-pressed={selected === choiceIndex}
                  disabled={Boolean(saving[key])}
                  onClick={() => {
                    void persistAnswer(question, index, choiceIndex);
                  }}
                  className="rounded-md bg-[var(--muted)]/50 px-2 py-1.5 text-left text-[var(--muted-foreground)] transition hover:bg-[var(--muted)] aria-pressed:bg-[color-mix(in_srgb,var(--primary)_10%,transparent)] aria-pressed:text-[var(--foreground)]"
                >
                  {String.fromCharCode(65 + choiceIndex)}. {choice}
                </button>
              ))}
            </div>
            {selected !== undefined ? (
              <p
                role="status"
                className={`mt-1 font-medium ${
                  verdicts[key]
                    ? "text-emerald-600 dark:text-emerald-400"
                    : "text-amber-600 dark:text-amber-400"
                }`}
              >
                {verdicts[key] ? t("Correct") : t("Incorrect")}
              </p>
            ) : null}
          </fieldset>
        );
      })}
      {reward ? (
        <p
          role="status"
          className="mt-3 flex items-center gap-1.5 font-medium text-amber-600 dark:text-amber-400"
        >
          <Star size={14} fill="currentColor" aria-hidden="true" />
          {t("Quiz stars: {{count}}", { count: reward.stars })}
        </p>
      ) : null}
    </>
  );
}