@anantagnanam/lms 0.1.0 → 0.3.0

package/astro/pages/study.astro

@@ -0,0 +1,180 @@
+---
+import Layout from "virtual:anantagnanam-lms/layout";
+import LearningShell from "../components/LearningShell.astro";
+import { lmsLearner, loginUrl, lessonUrl, LmsError } from "@anantagnanam/lms/server";
+import { basePath, loginPath } from "virtual:anantagnanam-lms/config";
+import type { Notebook, CourseAgenda, Page } from "@anantagnanam/lms/types";
+export const prerender = false;
+Astro.response.headers.set("Cache-Control", "private, no-store");
+Astro.response.headers.set("X-Robots-Tag", "noindex, nofollow");
+if (!Astro.locals.user)
+  return Astro.redirect(loginUrl(loginPath, Astro.url.pathname + Astro.url.search));
+let courses: Page<{ courseId: string; title: string; slug: string | null }> = {
+  items: [],
+  hasMore: false,
+};
+let notebook: Notebook | undefined;
+let agenda: CourseAgenda | undefined;
+let error = "";
+let agendaError = "";
+const courseId = Astro.url.searchParams.get("courseId");
+try {
+  courses = await lmsLearner(
+    Astro.locals,
+    "learner/study/courses",
+    { cursor: Astro.url.searchParams.get("cursor") ?? undefined, limit: 24 },
+    Astro.url.origin,
+  );
+  if (courseId) {
+    notebook = await lmsLearner(Astro.locals, "learner/notebook", { courseId }, Astro.url.origin);
+    try {
+      agenda = await lmsLearner(Astro.locals, "learner/agenda", { courseId }, Astro.url.origin);
+    } catch (cause) {
+      agendaError = cause instanceof Error ? cause.message : "Course agenda is unavailable.";
+    }
+  }
+} catch (cause) {
+  Astro.response.status = cause instanceof LmsError ? cause.status : 503;
+  error = cause instanceof Error ? cause.message : "Study tools are unavailable.";
+}
+---
+
+<Layout title="My notebook and agenda" robots="noindex, nofollow">
+  <LearningShell>
+    <h1>My notebook &amp; agenda</h1>
+    <p>Revisit important ideas and plan your next course activity.</p>
+    {error && <p role="alert">{error}</p>}
+    <details open={!courseId}>
+      <summary>Choose an enrolled course</summary>
+      <ul>
+        {courses.items.map((course) => (
+          <li>
+            <a
+              href={`?courseId=${encodeURIComponent(course.courseId)}`}
+              aria-current={course.courseId === courseId ? "page" : undefined}
+            >
+              {course.title}
+            </a>
+          </li>
+        ))}
+      </ul>
+      {!courses.items.length && !error && <p>No enrolled courses on this page.</p>}
+      {courses.hasMore && courses.cursor && (
+        <a href={`?cursor=${encodeURIComponent(courses.cursor)}`}>More courses →</a>
+      )}
+    </details>
+    {notebook && (
+      <>
+        <h2>{notebook.course.title}</h2>
+        <section
+          class="lms-learning-card"
+          data-lms-notebook
+          data-notebook={JSON.stringify(notebook)}
+          data-base-path={basePath}
+        >
+          <h3>Private notebook</h3>
+          <p>
+            Add notes from a lesson. Search this course’s notes, star important ideas, or archive
+            and restore entries. Saved lesson summaries are preserved below.
+          </p>
+          <div class="lms-actions">
+            <label>
+              Search notes <input type="search" maxlength={200} data-lms-note-search />
+            </label>
+            <label>
+              Show{" "}
+              <select data-lms-note-filter>
+                <option value="active">Active notes</option>
+                <option value="starred">Starred notes</option>
+                <option value="archived">Archived notes</option>
+              </select>
+            </label>
+            <button type="button" class="lms-btn lms-btn-outline" data-lms-notebook-refresh>
+              Reload saved notes
+            </button>
+          </div>
+          <p data-lms-feedback aria-live="polite"></p>
+          <div data-lms-note-list></div>
+          <noscript>
+            Enable JavaScript to search and edit notebook entries. Your learner data export also
+            includes these notes.
+          </noscript>
+        </section>
+        <section class="lms-learning-card" data-lms-agenda data-course-id={courseId}>
+          <h3>Course agenda</h3>
+          {agendaError && <p>{agendaError} Your private notebook remains available.</p>}
+          {agenda && (
+            <>
+              <p>
+                Assignment deadlines, live sessions and upcoming lesson releases from your enrolled
+                course edition. Lesson access and prerequisites still apply.
+              </p>
+              <div class="lms-actions">
+                <label>
+                  Display timezone{" "}
+                  <select data-lms-timezone>
+                    <option value="UTC">UTC</option>
+                  </select>
+                </label>
+                <label>
+                  <input type="checkbox" data-lms-agenda-upcoming /> Upcoming only
+                </label>
+                <button type="button" class="lms-btn lms-btn-outline" data-lms-calendar-download>
+                  Download upcoming calendar (.ics)
+                </button>
+              </div>
+              <p>
+                The download is a snapshot for your calendar app. It does not update automatically;
+                revisit the course for changes.
+              </p>
+              <p data-lms-feedback aria-live="polite"></p>
+              <ul class="lms-agenda-list">
+                {agenda.events.map((event) => (
+                  <li data-lms-agenda-event data-status={event.status}>
+                    <strong>
+                      {
+                        {
+                          assignment: "Assignment due",
+                          live: "Live session",
+                          release: "Lesson release",
+                        }[event.kind]
+                      }
+                      : {event.title}
+                    </strong>
+                    <p>
+                      <time datetime={event.startsAt} data-lms-date>
+                        {new Date(event.startsAt).toLocaleString("en-GB", { timeZone: "UTC" })} UTC
+                      </time>
+                      {event.endsAt && (
+                        <>
+                          {" "}
+                          –{" "}
+                          <time datetime={event.endsAt} data-lms-date>
+                            {new Date(event.endsAt).toLocaleString("en-GB", { timeZone: "UTC" })}{" "}
+                            UTC
+                          </time>
+                        </>
+                      )}
+                    </p>
+                    <p class="lms-badge">{event.status}</p>
+                    {event.available ? (
+                      <a href={lessonUrl(basePath, agenda.course.slug, event.lessonId)}>
+                        Open lesson →
+                      </a>
+                    ) : (
+                      <p>{event.reason}</p>
+                    )}
+                  </li>
+                ))}
+              </ul>
+              {!agenda.events.length && <p>This course has no dated activities.</p>}
+              <p data-lms-agenda-empty hidden>
+                No upcoming activities in this view.
+              </p>
+            </>
+          )}
+        </section>
+      </>
+    )}
+  </LearningShell>
+</Layout>

package/astro/quiz-drafts.ts

@@ -0,0 +1,23 @@
+import type { Answers } from "@anantagnanam/lms/types";
+import { DraftQueue, type DraftState } from "./draft-queue.js";
+export type { DraftState } from "./draft-queue.js";
+export interface DraftWrite {
+  answers: Answers;
+  expectedDraftRevision: number;
+}
+/** Retain the quiz interface while sharing the reliable writer with assignments. */
+export class QuizDraftQueue extends DraftQueue<Answers> {
+  constructor(
+    answers: Answers,
+    revision: number,
+    send: (write: DraftWrite) => Promise<{ draftRevision: number }>,
+    changed: (state: DraftState) => void,
+  ) {
+    super(
+      answers,
+      revision,
+      (write) => send({ answers: write.value, expectedDraftRevision: write.expectedDraftRevision }),
+      changed,
+    );
+  }
+}

package/astro/quiz-player.ts

@@ -0,0 +1,362 @@
+import type {
+  Answers,
+  ProgressSummary,
+  PublicEnrollment,
+  PublicQuizAttempt,
+} from "@anantagnanam/lms/types";
+import { QuizDraftQueue, type DraftState } from "./quiz-drafts.js";
+
+type Call = <T>(route: string, input: Record<string, unknown>, method?: string) => Promise<T>;
+type LessonState = { enrollment: PublicEnrollment; progress: ProgressSummary };
+const mounted = new WeakMap<HTMLElement, () => void>();
+function node<K extends keyof HTMLElementTagNameMap>(tag: K, text?: string, className?: string) {
+  const element = document.createElement(tag);
+  if (text !== undefined) element.textContent = text;
+  if (className) element.className = className;
+  return element;
+}
+function readAnswers(form: HTMLFormElement, attempt: PublicQuizAttempt): Answers {
+  const answers: Answers = {};
+  const values = new FormData(form);
+  for (const question of attempt.questions) {
+    const picked = values.getAll(question.id).map(String);
+    if (question.type === "multiple") answers[question.id] = picked;
+    else if (picked[0]) answers[question.id] = picked[0];
+  }
+  return answers;
+}
+function writeAnswers(form: HTMLFormElement, answers: Answers) {
+  for (const input of form.querySelectorAll<HTMLInputElement>("input[name]")) {
+    const value = answers[input.name];
+    if (input.type === "text") input.value = typeof value === "string" ? value : "";
+    else input.checked = Array.isArray(value) ? value.includes(input.value) : value === input.value;
+  }
+}
+function errorMessage(error: unknown) {
+  return error instanceof Error ? error.message : "Please try again.";
+}
+
+export function renderQuiz(root: HTMLElement, attempt: PublicQuizAttempt, call: Call) {
+  mounted.get(root)?.();
+  const content = root.querySelector<HTMLElement>("[data-lms-quiz-content]")!;
+  const feedback = (message: string, error = false) => {
+    if (!root.isConnected) return;
+    const target = root.querySelector<HTMLElement>("[data-lms-feedback]")!;
+    target.textContent = message;
+    target.dataset.tone = error ? "error" : "success";
+    target.setAttribute("role", error ? "alert" : "status");
+  };
+  const ids = {
+    courseId: root.dataset.courseId!,
+    lessonId: root.dataset.lessonId!,
+    attemptId: attempt.id,
+  };
+  const form = node("form");
+  const timer = node("p", "", "lms-quiz-timer");
+  timer.setAttribute("aria-live", "off");
+  form.append(timer);
+  for (const question of attempt.questions) {
+    const fieldset = node("fieldset", undefined, "lms-quiz-question");
+    fieldset.append(node("legend", question.prompt));
+    if (question.type === "short") {
+      const input = node("input");
+      input.name = question.id;
+      input.type = "text";
+      input.maxLength = 2000;
+      input.setAttribute("aria-label", "Your answer");
+      fieldset.append(input);
+    } else
+      for (const option of question.options) {
+        const label = node("label", undefined, "lms-quiz-option");
+        const input = node("input");
+        input.name = question.id;
+        input.type = question.type === "multiple" ? "checkbox" : "radio";
+        input.value = option.id;
+        label.append(input, node("span", option.text));
+        fieldset.append(label);
+      }
+    form.append(fieldset);
+  }
+  writeAnswers(form, attempt.answers);
+  const button = node("button", "Submit answers", "lms-btn");
+  button.type = "submit";
+  const status = node("p", "Saved answers loaded.", "lms-draft-status");
+  status.setAttribute("role", "status");
+  status.setAttribute("aria-live", "polite");
+  const retry = node("button", "Retry saving", "lms-btn lms-btn-outline");
+  retry.type = "button";
+  retry.hidden = true;
+  const review = node("button", "Review saved answers", "lms-btn lms-btn-outline");
+  review.type = "button";
+  review.hidden = true;
+  const recovery = node("div", undefined, "lms-notice");
+  recovery.hidden = true;
+  form.append(status, retry, review, recovery, button);
+  content.replaceChildren(form);
+  let interval: ReturnType<typeof setInterval> | undefined;
+  let debounce: ReturnType<typeof setTimeout> | undefined;
+  let submitting = false;
+  let uncertainSubmission = false;
+  let ended = false;
+  let timeoutSent = false;
+  const labels: Record<DraftState, string> = {
+    pending: "Unsaved answers · waiting to save…",
+    saving: "Saving answers…",
+    saved: "All answers saved.",
+    failed: "Answers could not be saved. Keep this page open and retry.",
+    conflict: "Saved answers changed in another tab. Review them before continuing.",
+  };
+  const queue = new QuizDraftQueue(
+    attempt.answers,
+    attempt.draftRevision,
+    (write) => call("learner/quiz/draft", { ...ids, ...write }),
+    (state) => {
+      status.textContent = labels[state];
+      status.dataset.tone = state === "failed" || state === "conflict" ? "error" : "success";
+      retry.hidden = state !== "failed";
+      review.hidden = state !== "conflict";
+    },
+  );
+  const atRisk = () =>
+    !ended && (queue.dirty || queue.state === "conflict" || submitting || uncertainSubmission);
+  const beforeUnload = (event: BeforeUnloadEvent) => {
+    if (atRisk()) event.preventDefault();
+  };
+  const beforeNavigate = (event: Event) => {
+    if (atRisk() && !window.confirm("Some quiz answers may not be saved. Leave this page?"))
+      event.preventDefault();
+  };
+  const cleanup = () => {
+    ended = true;
+    clearInterval(interval);
+    clearTimeout(debounce);
+    queue.dispose();
+    window.removeEventListener("beforeunload", beforeUnload);
+    document.removeEventListener("astro:before-preparation", beforeNavigate);
+    document.removeEventListener("astro:before-swap", cleanup);
+    observer.disconnect();
+    mounted.delete(root);
+  };
+  const observer = new MutationObserver(() => {
+    if (!form.isConnected) cleanup();
+  });
+  observer.observe(document.body, { childList: true, subtree: true });
+  window.addEventListener("beforeunload", beforeUnload);
+  document.addEventListener("astro:before-preparation", beforeNavigate);
+  document.addEventListener("astro:before-swap", cleanup, { once: true });
+  mounted.set(root, cleanup);
+
+  const finish = (final: PublicQuizAttempt, progress: ProgressSummary) => {
+    if (ended) return;
+    cleanup();
+    feedback(
+      final.status === "expired"
+        ? "The quiz time limit expired. Your saved attempt is retained."
+        : `${final.passed ? "Passed" : "Not passed yet"} · ${final.percent}%`,
+    );
+    const outcome = node("div");
+    for (const item of final.feedback) {
+      const section = node("div", undefined, "lms-notice");
+      const question = attempt.questions.find((entry) => entry.id === item.questionId);
+      section.append(
+        node("strong", `${item.correct ? "✓" : "○"} ${question?.prompt ?? "Question"}`),
+      );
+      if (item.explanation) section.append(node("p", item.explanation));
+      outcome.append(section);
+    }
+    content.replaceChildren(outcome);
+    const start = root.querySelector<HTMLButtonElement>("[data-lms-quiz-start]");
+    if (start) {
+      start.hidden = final.passed;
+      start.disabled = false;
+      start.textContent = "Try another attempt";
+    }
+    if (final.passed) {
+      const courseUrl = root.dataset.courseUrl!;
+      const link = node(
+        "a",
+        progress.nextLessonId ? "Continue learning →" : "Course overview →",
+        "lms-btn",
+      );
+      link.href = progress.nextLessonId
+        ? `${courseUrl}/lessons/${encodeURIComponent(progress.nextLessonId)}`
+        : courseUrl;
+      if (progress.blockedLessonId) {
+        const blocked = progress.availability[progress.blockedLessonId];
+        content.append(
+          node(
+            "p",
+            `${blocked?.reason ?? "The next lesson is unavailable."}${blocked?.releaseAt ? ` Available from ${new Date(blocked.releaseAt).toLocaleString(undefined, { timeZoneName: "short" })}.` : ""}`,
+            "lms-notice",
+          ),
+        );
+      }
+      content.append(link);
+    }
+  };
+  const fetchAttempt = async (expiredByServer = false) => {
+    const state = await call<LessonState>("learner/lesson", ids, "GET");
+    const remote = state.enrollment.progress[ids.lessonId]?.quizAttempts.find(
+      (item) => item.id === attempt.id,
+    );
+    if (!remote)
+      throw new Error(
+        "This attempt could not be found. Keep this page open and contact an instructor.",
+      );
+    if (remote.status !== "in_progress" || expiredByServer) {
+      finish(
+        remote.status === "in_progress" ? { ...remote, status: "expired" } : remote,
+        state.progress,
+      );
+      return null;
+    }
+    return remote;
+  };
+  const save = async () => {
+    try {
+      await queue.flush();
+      if (!ended) feedback("Answers saved.");
+    } catch (error) {
+      if (ended) return;
+      feedback(errorMessage(error), true);
+      if (["QUIZ_EXPIRED", "ATTEMPT_CLOSED"].includes((error as { code?: string })?.code ?? "")) {
+        try {
+          await fetchAttempt((error as { code?: string }).code === "QUIZ_EXPIRED");
+        } catch {
+          /* The visible save error and retry remain. */
+        }
+      }
+    }
+  };
+  const showConflict = (remote: PublicQuizAttempt) => {
+    if (ended) return;
+    queue.conflict();
+    clearTimeout(debounce);
+    recovery.hidden = false;
+    recovery.replaceChildren(
+      node("h3", "Review the saved draft"),
+      node(
+        "p",
+        "Compare the server answers below with your answers in the form. Choose which set to keep. A newer change in another tab will require another review.",
+      ),
+    );
+    for (const question of attempt.questions) {
+      const value = remote.answers[question.id];
+      const values = Array.isArray(value) ? value : value ? [value] : [];
+      recovery.append(
+        node(
+          "p",
+          `${question.prompt}: ${values.map((item) => question.options.find((option) => option.id === item)?.text ?? item).join(", ") || "Unanswered"}`,
+        ),
+      );
+    }
+    const useSaved = node("button", "Use saved answers", "lms-btn lms-btn-outline");
+    useSaved.type = "button";
+    const keepLocal = node("button", "Keep my answers and save", "lms-btn");
+    keepLocal.type = "button";
+    const choose = (keep: boolean) => {
+      queue.update(readAnswers(form, attempt));
+      queue.reconcile(remote.answers, remote.draftRevision, keep);
+      if (!keep) writeAnswers(form, remote.answers);
+      recovery.hidden = true;
+      feedback(keep ? "Saving your chosen answers…" : "Saved answers loaded.");
+      if (keep) void save();
+    };
+    useSaved.addEventListener("click", () => choose(false));
+    keepLocal.addEventListener("click", () => choose(true));
+    recovery.append(useSaved, keepLocal);
+  };
+  review.addEventListener("click", async () => {
+    review.disabled = true;
+    feedback("Loading saved answers for review…");
+    try {
+      const remote = await fetchAttempt();
+      if (remote) showConflict(remote);
+    } catch (error) {
+      feedback(errorMessage(error), true);
+    } finally {
+      review.disabled = false;
+    }
+  });
+  retry.addEventListener("click", () => void save());
+  form.addEventListener("input", () => {
+    queue.update(readAnswers(form, attempt));
+    clearTimeout(debounce);
+    if (!submitting && !["failed", "conflict"].includes(queue.state))
+      debounce = setTimeout(() => {
+        if (!ended) void save();
+      }, 700);
+  });
+  form.addEventListener("submit", async (event) => {
+    event.preventDefault();
+    if (submitting || ended) return;
+    clearTimeout(debounce);
+    const answers = readAnswers(form, attempt);
+    queue.update(answers);
+    submitting = true;
+    button.disabled = true;
+    retry.disabled = true;
+    review.disabled = true;
+    recovery.hidden = true;
+    form.querySelectorAll("fieldset").forEach((fieldset) => {
+      fieldset.disabled = true;
+    });
+    feedback("Checking your answers…");
+    try {
+      await queue.flush();
+      if (ended) return;
+      uncertainSubmission = true;
+      const result = await call<{ attempt: PublicQuizAttempt; progress: ProgressSummary }>(
+        "learner/quiz/submit",
+        { ...ids, answers, expectedDraftRevision: queue.revision },
+      );
+      finish(result.attempt, result.progress);
+    } catch (error) {
+      if (ended) return;
+      feedback(`${errorMessage(error)} Checking the original attempt…`, true);
+      try {
+        const remote = await fetchAttempt((error as { code?: string })?.code === "QUIZ_EXPIRED");
+        if (remote && !ended) {
+          uncertainSubmission = false;
+          if (queue.state === "conflict" || remote.draftRevision !== queue.revision)
+            showConflict(remote);
+          feedback(
+            `${errorMessage(error)} Your answers remain in this form. Retry this attempt when ready.`,
+            true,
+          );
+        }
+      } catch {
+        feedback(
+          `${errorMessage(error)} Could not confirm the attempt status. Keep this page open and retry this same attempt.`,
+          true,
+        );
+      }
+    } finally {
+      submitting = false;
+      button.disabled = false;
+      retry.disabled = false;
+      review.disabled = false;
+      form.querySelectorAll("fieldset").forEach((fieldset) => {
+        fieldset.disabled = false;
+      });
+    }
+  });
+  if (attempt.expiresAt) {
+    const tick = () => {
+      if (ended) return;
+      const remaining = Math.max(
+        0,
+        Math.ceil((Date.parse(attempt.expiresAt!) - Date.now()) / 1000),
+      );
+      timer.textContent = remaining
+        ? `Time remaining ${Math.floor(remaining / 60)}:${String(remaining % 60).padStart(2, "0")}`
+        : "Time limit reached. Check the attempt result or retry to confirm its status.";
+      if (!remaining && !timeoutSent) {
+        timeoutSent = true;
+        form.requestSubmit();
+      }
+    };
+    interval = setInterval(tick, 1000);
+    tick();
+  } else timer.textContent = "Take your time. This quiz is untimed.";
+}