Skip to content

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

20.6 KB
Raw Blame
"use client";

/**
 * The answer card for a mastery question.
 *
 * Its sibling `AskUserOptions` exists to unblock a decision: it shows a label
 * and, under it, whatever else the model wanted to say about that choice. A
 * mastery question does not fit that — its options *are* bodies of text, and
 * they are numbered — so the generic card printed the letter twice, once as
 * the badge and once as the label, above the answer it was labelling.
 *
 * The look follows the rule the mastery surface already set for itself (see
 * `mastery-theme.css`): state is carried by *form*, not by a skin. So there is
 * no boxed panel, no filled rows and no coloured verdict banner — a question
 * is a rule down the left margin, a prompt, and lines of text you can pick.
 * The rule is what changes: neutral while it is the learner's move, primary or
 * destructive once the gate has ruled. It should read like a question on a
 * page, not like a form to fill in.
 */

import { memo, useCallback, useEffect, useRef, useState } from "react";
import { useTranslation } from "react-i18next";

import InlineMarkdown from "@/components/common/InlineMarkdown";
import { useCardSubmission } from "@/hooks/use-card-submission";
import { REPLY_NOT_DELIVERED } from "@/lib/ask-user-state";
import {
  MASTERY_ANSWER_REJECTED_MESSAGE,
  type MasteryGradeResult,
  type MasteryQuestion,
} from "@/lib/mastery-question";

/** Difficulty is a three-point scale; anything else is not shown. */
const DIFFICULTY_LABELS: Record<string, string> = {
  easy: "Easy",
  medium: "Medium",
  hard: "Hard",
};

type OptionState = "idle" | "picked" | "correct" | "wrong";

function OptionRow({
  option,
  index,
  state,
  disabled,
  onPick,
}: {
  option: { label: string; body: string };
  index: number;
  state: OptionState;
  disabled: boolean;
  onPick: () => void;
}) {
  const letter = option.label || String.fromCharCode(65 + index);
  // The marker carries the state on its own: outline → filled, in whatever
  // colour the verdict gives it. The row never becomes a coloured block.
  const marker =
    state === "correct" || state === "picked"
      ? "border-[var(--primary)] bg-[var(--primary)] text-[var(--primary-foreground)]"
      : state === "wrong"
        ? "border-[var(--destructive)] bg-[var(--destructive)] text-[var(--destructive-foreground)]"
        : "border-[var(--border)] text-[var(--muted-foreground)] group-hover:border-[color-mix(in_srgb,var(--foreground)_35%,transparent)] group-hover:text-[var(--foreground)]";
  const body =
    state === "wrong"
      ? "text-[var(--muted-foreground)]"
      : "text-[var(--foreground)]";
  return (
    <button
      type="button"
      onClick={onPick}
      disabled={disabled}
      className={
        "group -mx-2 flex items-baseline gap-3 rounded-lg px-2 py-1.5 text-left transition-colors " +
        (disabled
          ? "cursor-default"
          : "hover:bg-[color-mix(in_srgb,var(--foreground)_3.5%,transparent)]")
      }
    >
      <span
        className={
          "relative top-px flex h-[19px] w-[19px] shrink-0 items-center justify-center rounded-full border text-[10.5px] font-semibold transition-colors " +
          marker
        }
      >
        {letter}
      </span>
      {/* The body is the option. It is never printed beside its own letter. */}
      <span className={"min-w-0 flex-1 text-[13.5px] leading-relaxed " + body}>
        <InlineMarkdown content={option.body} />
      </span>
    </button>
  );
}

interface MasteryQuestionCardProps {
  question: MasteryQuestion;
  /** The gate's ruling, once it has been made. */
  grade: MasteryGradeResult | null;
  /** The learner has already answered this card (this turn or an earlier one). */
  answered: boolean;
  /** The learner dropped this question; the engine closed it ungraded. */
  skipped?: boolean;
  /** What they answered, when the transcript knows it. */
  submittedAnswer: string;
  /** Unique server rejection event; changes reopen an optimistically sent card. */
  rejectionKey?: string;
  onSubmit: (payload: {
    text?: string;
    answers?: Array<{ questionId: string; text: string }>;
  }) => void | boolean | Promise<void | boolean>;
  /** Drop this question and let the tutor move on. Absent where the surface
   *  cannot start a turn of its own, which hides the control entirely. */
  onSkip?: (questionId: string) => void | boolean | Promise<void | boolean>;
  onChallenge?: (questionId: string) => void | boolean | Promise<void | boolean>;
}

/** The same native controls, with submission owned by their group instead. */
interface GroupInput {
  locked: boolean;
  onChange: (questionId: string, answer: string, sourceAvailable: boolean) => void;
}

const SingleMasteryQuestionCard = memo(function SingleMasteryQuestionCard({
  question, grade, answered, skipped, submittedAnswer, onSubmit, onSkip,
  onChallenge, groupInput, rejectionKey,
}: MasteryQuestionCardProps & { groupInput?: GroupInput }) {
  const { t } = useTranslation();
  const [picked, setPicked] = useState<string>(() => grade?.final === false ? grade.learnerAnswer : "");
  const [skipping, setSkipping] = useState(false);
  const [sourceUnavailable, setSourceUnavailable] = useState(false);
  const [freeText, setFreeText] = useState(() => grade?.final === false ? grade.learnerAnswer : "");
  const [freeSelected, setFreeSelected] = useState(false);
  const acknowledgementKey = grade ? grade.receiptKey ?? JSON.stringify(grade) : undefined;
  const { sending, failed: sendFailed, submit } = useCardSubmission(onSubmit, rejectionKey, acknowledgementKey);
  const textareaRef = useRef<HTMLTextAreaElement>(null);

  useEffect(() => {
    if (freeSelected) textareaRef.current?.focus();
  }, [freeSelected]);

  const hasChoices = question.options.length > 0;
  const usesFreeText = freeSelected || !hasChoices;
  const answer = usesFreeText ? freeText.trim() : picked;
  // Skipping settles the card exactly as answering does: the engine closed the
  // question, so there is nothing left on it to send.
  const settled = (answered && grade?.final !== false) || skipped === true;
  const ungraded = grade?.result === "ungraded";
  const locked = settled || sending || skipping || groupInput?.locked === true;

  const onGroupChange = groupInput?.onChange;
  useEffect(() => {
    onGroupChange?.(question.questionId, answer, !sourceUnavailable);
  }, [onGroupChange, question.questionId, answer, sourceUnavailable]);

  const handleSkip = useCallback(() => {
    if (locked || !onSkip) return;
    setSkipping(true);
    void Promise.resolve(onSkip(question.questionId)).then((accepted) => {
      // Same rule as an answer: only an explicit refusal reopens the card.
      if (accepted === false) setSkipping(false);
    });
  }, [locked, onSkip, question.questionId]);

  const handleSubmit = useCallback(() => {
    if (locked || !answer || sourceUnavailable) return;
    void submit({
      text: answer,
      answers: [{ questionId: question.questionId, text: answer }],
    });
  }, [answer, locked, sourceUnavailable, submit, question.questionId]);

  // Which answer to treat as the learner's, preferring what the graded record
  // committed over what this browser happens to remember.
  const learnerAnswer = grade?.learnerAnswer || submittedAnswer || answer;
  const difficultyLabel = DIFFICULTY_LABELS[question.difficulty] ?? "";
  const meta = [
    question.objectiveName,
    difficultyLabel ? t(difficultyLabel) : "",
    question.attempt > 1
      ? t("Attempt {{count}}", { count: question.attempt })
      : "",
  ].filter(Boolean);

  // The rule down the left margin is the whole status indicator.
  const rule = ungraded ? "border-dashed border-[var(--border)]" : grade
    ? grade.isCorrect
      ? "border-[var(--primary)]"
      : "border-[var(--destructive)]"
    : skipped
      ? // Closed, but nothing was judged — a dashed rule says "set aside"
        // where a solid one would claim a verdict that was never made.
        "border-dashed border-[var(--border)]"
      : "border-[var(--border)]";

  const optionState = (option: { label: string }): OptionState => {
    if (grade) {
      if (ungraded) return "idle";
      if (option.label && option.label === grade.correctLabel) return "correct";
      if (option.label && option.label === learnerAnswer && !grade.isCorrect)
        return "wrong";
      return "idle";
    }
    if (settled) return option.label === learnerAnswer ? "picked" : "idle";
    return !freeSelected && option.label === picked ? "picked" : "idle";
  };

  return (
    <div className={"my-4 border-l-2 pl-4 transition-colors sm:pl-5 " + rule}>
      {meta.length > 0 ? (
        <div className="text-[11px] leading-5 text-[var(--muted-foreground)]">
          {meta.join(" · ")}
        </div>
      ) : null}

      <div className="mt-0.5 font-serif text-[15.5px] font-semibold leading-relaxed tracking-[-0.01em] text-[var(--foreground)]">
        <InlineMarkdown content={question.prompt} />
      </div>
      {question.visual && <div className="mt-3 space-y-2 text-xs text-[var(--muted-foreground)]">
        <p>{grade?.independent === false || question.visual.hintsUsed || question.visual.answerCues !== "none" ? t("Guided visual practice — this does not demonstrate independent mastery.") : t("Visual practice with the original source.")}</p>
        {sourceUnavailable && <p role="alert">{t("The source image is unavailable. Open the source or ask your tutor to inspect its current version.")}</p>}
        {question.visual.keyStatus !== "verified" && <p>{t("The reference key is uncertain. This practice will remain ungraded.")}</p>}
        {question.visual.pixelsInspected === false && <p>{t("Current model input has no verified source pixels. Retrieve the image again with a vision-capable model before grading.")}</p>}
        {question.visual.sources.map((source, index) => <figure key={`${source.imageUrl}-${index}`}>
          {/* Authenticated source endpoints need the browser's own cookies. */}
          <a href={source.imageUrl} target="_blank" rel="noreferrer"><img src={source.imageUrl} alt={t("Original source evidence")} onError={() => setSourceUnavailable(true)} className="max-h-80 max-w-full object-contain" /></a>
          <figcaption><a className="underline" href={source.url} target="_blank" rel="noreferrer">{source.sourcePath}{source.page ? ` · ${t("Page")} ${source.page}` : ""}</a></figcaption>
        </figure>)}
      </div>}

      {hasChoices ? (
        <div className="mt-2.5 flex flex-col gap-0.5">
          {question.options.map((option, idx) => (
            <OptionRow
              key={`${option.label}-${idx}`}
              option={option}
              index={idx}
              state={optionState(option)}
              disabled={locked}
              onPick={() => {
                setFreeSelected(false);
                setPicked(option.label);
              }}
            />
          ))}
        </div>
      ) : null}

      {question.allowFreeText && !settled ? (
        <div className="mt-1.5">
          {freeSelected || !hasChoices ? (
            <textarea
              ref={textareaRef}
              aria-label={question.prompt}
              value={freeText}
              onChange={(event) => setFreeText(event.target.value)}
              placeholder={t("Write your answer…")}
              rows={hasChoices ? 2 : 3}
              disabled={locked}
              className="w-full resize-y rounded-lg border border-[var(--border)] bg-transparent px-2.5 py-2 text-[13.5px] leading-relaxed text-[var(--foreground)] outline-none transition-colors placeholder:text-[color-mix(in_srgb,var(--muted-foreground)_75%,transparent)] focus:border-[color-mix(in_srgb,var(--foreground)_35%,transparent)] disabled:opacity-60"
            />
          ) : (
            <button
              type="button"
              onClick={() => setFreeSelected(true)}
              disabled={locked}
              className="-mx-2 flex items-baseline gap-3 rounded-lg px-2 py-1.5 text-left text-[13px] text-[var(--muted-foreground)] transition-colors hover:bg-[color-mix(in_srgb,var(--foreground)_3.5%,transparent)] hover:text-[var(--foreground)] disabled:cursor-default"
            >
              <span className="relative top-px flex h-[19px] w-[19px] shrink-0 items-center justify-center rounded-full border border-dashed border-[var(--border)] text-[10.5px] font-semibold">
                +
              </span>
              {t("Answer in my own words")}
            </button>
          )}
        </div>
      ) : null}

      {/* The ruling, as prose under a hairline — not another coloured panel. */}
      {grade ? (
        <div className="mt-3 border-t border-[var(--border)] pt-2.5">
          <div className="text-[12.5px] leading-relaxed">
            <span
              className={
                "font-semibold " +
                (ungraded ? "text-[var(--muted-foreground)]" : grade.isCorrect
                  ? "text-[var(--primary)]"
                  : "text-[var(--destructive)]")
              }
            >
              {ungraded ? t("Ungraded — mastery unchanged") : grade.result === "partial" ? t("Partially correct") : grade.isCorrect ? t("Correct") : t("Not quite")}
            </span>
            {!ungraded && !grade.isCorrect && grade.correctLabel ? (
              <span className="text-[var(--foreground)]">
                {" · "}
                {t("Answer: {{label}}", { label: grade.correctLabel })}
              </span>
            ) : null}
          </div>
          {grade.explanation ? (
            <div className="mt-1 text-[12.5px] leading-relaxed text-[var(--muted-foreground)]">
              <InlineMarkdown content={grade.explanation} />
            </div>
          ) : null}
          {grade.feedback && grade.feedback !== grade.explanation && <div className="mt-1 text-[12.5px]"><InlineMarkdown content={grade.feedback} /></div>}
          {onChallenge && <button type="button" className="mt-2 text-xs underline" onClick={() => onChallenge(question.questionId)}>{t("Review or challenge this assessment")}</button>}
        </div>
      ) : null}

      {/* Footer: only while the question is still the learner's move. */}
      {!groupInput && (!settled ? (
        <div className="mt-3 flex items-center justify-between gap-3">
          <span
            className={
              "text-[11px] " +
              (sendFailed
                ? "text-[var(--destructive)]"
                : "text-[var(--muted-foreground)]")
            }
          >
            {sending
              ? t("Sending your answers…")
              : sendFailed
                ? t(rejectionKey ? MASTERY_ANSWER_REJECTED_MESSAGE : REPLY_NOT_DELIVERED)
                : hasChoices
                  ? t("Pick the option you think is right.")
                  : t("Write your answer to continue.")}
          </span>
          <div className="flex shrink-0 items-center gap-1">
            {/* Not a dead end: the engine holds one open question per path, so
                without this the tutor's next question is this same one again.
                Quiet, because skipping is the rarer move. */}
            {onSkip ? (
              <button
                type="button"
                onClick={handleSkip}
                disabled={locked}
                className="rounded-md px-2 py-1.5 text-[12px] text-[var(--muted-foreground)] transition-colors hover:bg-[color-mix(in_srgb,var(--foreground)_4%,transparent)] hover:text-[var(--foreground)] disabled:cursor-not-allowed disabled:opacity-40"
              >
                {skipping ? t("Skipping…") : t("Skip this one")}
              </button>
            ) : null}
            <button
              type="button"
              onClick={handleSubmit}
              disabled={locked || !answer || sourceUnavailable}
              className="rounded-md bg-[var(--primary)] px-3 py-1.5 text-[12px] font-medium text-[var(--primary-foreground)] transition-opacity hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-40"
            >
              {t("Submit")}
            </button>
          </div>
        </div>
      ) : skipped ? (
        <div className="mt-2.5 text-[11px] text-[var(--muted-foreground)]">
          {t("Skipped — no attempt was recorded for this question.")}
        </div>
      ) : !grade ? (
        <div className="mt-2.5 text-[11px] text-[var(--muted-foreground)]">
          {t("Answer submitted — your tutor is checking it.")}
        </div>
      ) : null)}
    </div>
  );
});

function GroupedMasteryQuestionCard({
  question, grade, answered, skipped, onSubmit, onSkip, onChallenge, rejectionKey,
}: MasteryQuestionCardProps) {
  const { t } = useTranslation();
  const [answers, setAnswers] = useState<Record<string, { text: string; available: boolean }>>({});
  const [skipping, setSkipping] = useState(false);
  const [skipFailed, setSkipFailed] = useState(false);
  const questions = question.questions ?? [];
  const acknowledgementKey = grade ? grade.receiptKey ?? JSON.stringify(grade.results ?? []) : undefined;
  const { sending, failed, submit } = useCardSubmission(onSubmit, rejectionKey, acknowledgementKey);
  const settled = ((answered || Boolean(grade)) && grade?.complete !== false && grade?.final !== false) || skipped === true;
  const locked = settled || sending || skipping;
  const remaining = questions.filter((part) => !grade?.results?.some((result) => result.questionId === part.questionId && result.final !== false));
  const drafted = remaining.filter((part) => Boolean(answers[part.questionId]?.text));
  const ready = questions.length >= 2 && drafted.length > 0 && drafted.every((part) => answers[part.questionId]?.available);

  const updateAnswer = useCallback((questionId: string, text: string, available: boolean) => {
    setAnswers((current) => current[questionId]?.text === text && current[questionId]?.available === available
      ? current : { ...current, [questionId]: { text, available } });
  }, []);

  const handleSubmit = () => {
    if (locked || !ready) return;
    const parts = drafted.map((part) => ({ questionId: part.questionId, text: answers[part.questionId].text }));
    void submit({ text: parts.map((part) => `${questions.findIndex((question) => question.questionId === part.questionId) + 1}. ${part.text}`).join("\n"), answers: parts });
  };

  const handleSkip = async () => {
    if (locked || !onSkip) return;
    setSkipping(true);
    setSkipFailed(false);
    try {
      if (await onSkip(question.questionId) === false) {
        setSkipping(false);
        setSkipFailed(true);
      }
    } catch {
      setSkipping(false);
      setSkipFailed(true);
    }
  };

  return <section className="my-4" aria-label={question.prompt}>
    {question.prompt && <div className="font-serif font-semibold"><InlineMarkdown content={question.prompt} /></div>}
    {questions.map((part) => {
      const partGrade = grade?.results?.find((result) => result.questionId === part.questionId) ?? null;
      return <SingleMasteryQuestionCard key={part.questionId} question={part} grade={partGrade}
        answered={settled || (Boolean(partGrade) && partGrade?.final !== false)} skipped={skipped} submittedAnswer={partGrade?.learnerAnswer ?? ""}
        onSubmit={onSubmit} onChallenge={onChallenge} groupInput={{ locked, onChange: updateAnswer }} />;
    })}
    {!settled ? <div className="mt-3 flex items-center justify-between gap-3">
      <span className={failed || skipFailed ? "text-xs text-[var(--destructive)]" : "text-xs text-[var(--muted-foreground)]"}>
        {sending ? t("Sending your answers…") : failed || skipFailed
          ? t(failed && rejectionKey ? MASTERY_ANSWER_REJECTED_MESSAGE : REPLY_NOT_DELIVERED)
          : t("Write your answer to continue.")}
      </span>
      <div className="flex shrink-0 items-center gap-1">
        {onSkip && <button type="button" onClick={() => void handleSkip()} disabled={locked}
          className="rounded-md px-2 py-1.5 text-xs text-[var(--muted-foreground)] disabled:opacity-40">
          {skipping ? t("Skipping…") : t("Skip this one")}
        </button>}
        <button type="button" onClick={handleSubmit} disabled={locked || !ready}
          className="rounded-md bg-[var(--primary)] px-3 py-1.5 text-xs font-medium text-[var(--primary-foreground)] disabled:opacity-40">
          {t("Submit")}
        </button>
      </div>
    </div> : skipped ? <p className="text-xs text-[var(--muted-foreground)]">{t("Skipped — no attempt was recorded for this question.")}</p>
      : !grade ? <p className="text-xs text-[var(--muted-foreground)]">{t("Answer submitted — your tutor is checking it.")}</p> : null}
  </section>;
}

export const MasteryQuestionCard = memo(function MasteryQuestionCard(props: MasteryQuestionCardProps) {
  return props.question.questionType === "group"
    ? <GroupedMasteryQuestionCard key={props.question.questionId} {...props} />
    : <SingleMasteryQuestionCard {...props} />;
});

export default MasteryQuestionCard;