@anantagnanam/lms 0.1.0 → 0.2.0

package/astro/pages/paths.astro

@@ -0,0 +1,73 @@
+---
+import Layout from "virtual:anantagnanam-lms/layout";
+import LearningShell from "../components/LearningShell.astro";
+import { lmsPublic, courseUrl, loginUrl, LmsError } from "@anantagnanam/lms/server";
+import { basePath, loginPath } from "virtual:anantagnanam-lms/config";
+import type { Page, PublicPath } from "@anantagnanam/lms/types";
+export const prerender = false;
+Astro.response.headers.set("Cache-Control", "private, no-store");
+let page: Page<PublicPath> = { items: [], hasMore: false };
+let error = "";
+try {
+  page = await lmsPublic<typeof page>(
+    Astro.locals,
+    "paths",
+    { cursor: Astro.url.searchParams.get("cursor") ?? undefined },
+    Astro.url.origin,
+  );
+} catch (cause) {
+  Astro.response.status = cause instanceof LmsError ? cause.status : 503;
+  error = cause instanceof Error ? cause.message : "Learning paths unavailable.";
+}
+const next = new URL(Astro.url);
+next.searchParams.set("cursor", page.cursor ?? "");
+---
+
+<Layout title="Learning paths">
+  <LearningShell>
+    <h1>Learning paths</h1>
+    <p class="lms-lead">
+      Follow an ordered program of courses and track your progress in your library.
+    </p>
+    <p>
+      Join a path to save its course list. Enroll in each course separately; approval and
+      prerequisites still apply.
+    </p>
+    {error && <p role="alert">{error}</p>}
+    {!error && !page.items.length && <p>No learning paths have been published yet.</p>}
+    {page.items.map((path) => (
+      <article class="lms-learning-card">
+        <h2>{path.title}</h2>
+        <p class="lms-text">{path.description}</p>
+        <ol>
+          {path.courses.map((course) => (
+            <li>
+              {course ? (
+                <a href={courseUrl(basePath, course.slug)}>{course.title}</a>
+              ) : (
+                "Course currently unavailable"
+              )}
+            </li>
+          ))}
+        </ol>
+        {Astro.locals.user ? (
+          <form data-lms-route="learner/path/join">
+            <input type="hidden" name="pathId" value={path.id} />
+            <button class="lms-btn" type="submit">
+              Join path
+            </button>
+            <a class="lms-btn lms-btn-outline" href={`${basePath}/my-learning/library`}>
+              View my paths
+            </a>
+            <p data-lms-feedback aria-live="polite"></p>
+          </form>
+        ) : (
+          <a class="lms-btn" href={loginUrl(loginPath, Astro.url.pathname)}>
+            Sign in to join
+          </a>
+        )}
+      </article>
+    ))}
+    {page.hasMore && page.cursor && <a href={next.href}>More learning paths →</a>}
+  </LearningShell>
+</Layout>

package/astro/quiz-drafts.ts

@@ -0,0 +1,87 @@
+import type { Answers } from "@anantagnanam/lms/types";
+
+export type DraftState = "saved" | "pending" | "saving" | "failed" | "conflict";
+export interface DraftWrite {
+  answers: Answers;
+  expectedDraftRevision: number;
+}
+const fingerprint = (answers: Answers) =>
+  JSON.stringify(Object.entries(answers).sort(([a], [b]) => a.localeCompare(b)));
+
+/** One writer per form. Keep an unacknowledged request intact for lost-response retries. */
+export class QuizDraftQueue {
+  revision: number;
+  state: DraftState = "saved";
+  private latest: Answers;
+  private acknowledged: string;
+  private retry?: DraftWrite;
+  private running?: Promise<void>;
+  private disposed = false;
+  constructor(
+    answers: Answers,
+    revision: number,
+    private send: (write: DraftWrite) => Promise<{ draftRevision: number }>,
+    private changed: (state: DraftState) => void,
+  ) {
+    this.latest = structuredClone(answers);
+    this.acknowledged = fingerprint(answers);
+    this.revision = revision;
+  }
+  get dirty() {
+    return !!this.retry || fingerprint(this.latest) !== this.acknowledged;
+  }
+  private emit(state: DraftState) {
+    this.state = state;
+    if (!this.disposed) this.changed(state);
+  }
+  update(answers: Answers) {
+    this.latest = structuredClone(answers);
+    if (!["failed", "conflict", "saving"].includes(this.state))
+      this.emit(this.dirty ? "pending" : "saved");
+  }
+  flush(): Promise<void> {
+    if (this.disposed) return Promise.reject(new Error("This quiz form has closed."));
+    if (this.state === "conflict")
+      return Promise.reject(new Error("Review the saved answers before continuing."));
+    if (this.running) return this.running;
+    this.running = this.drain().finally(() => {
+      this.running = undefined;
+    });
+    return this.running;
+  }
+  private async drain() {
+    while (this.dirty && !this.disposed) {
+      const write = this.retry ?? {
+        answers: structuredClone(this.latest),
+        expectedDraftRevision: this.revision,
+      };
+      this.retry = write;
+      this.emit("saving");
+      try {
+        const result = await this.send(structuredClone(write));
+        this.revision = result.draftRevision;
+        this.acknowledged = fingerprint(write.answers);
+        this.retry = undefined;
+      } catch (error) {
+        this.emit((error as { code?: string })?.code === "DRAFT_CONFLICT" ? "conflict" : "failed");
+        throw error;
+      }
+    }
+    this.emit(this.dirty ? "pending" : "saved");
+  }
+  /** Called only after the learner reviews the current remote draft. */
+  conflict() {
+    this.emit("conflict");
+  }
+  reconcile(answers: Answers, revision: number, keepLocal: boolean) {
+    if (this.running) throw new Error("Wait for the current save to finish.");
+    this.revision = revision;
+    this.acknowledged = fingerprint(answers);
+    this.retry = undefined;
+    if (!keepLocal) this.latest = structuredClone(answers);
+    this.emit(this.dirty ? "pending" : "saved");
+  }
+  dispose() {
+    this.disposed = true;
+  }
+}

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.";
+}

package/astro/styles.css

@@ -1286,3 +1286,15 @@
     display: none;
   }
 }
+.lms-root .lms-lock-note {
+  display: block;
+  margin-block: 0.4rem;
+  color: #526357;
+  font-size: 0.85rem;
+}
+.lms-root .lms-locked-lesson {
+  padding: 0.7rem 0.9rem;
+}
+.lms-root .lms-draft-status[data-tone="error"] {
+  color: #9d2837;
+}

package/dist/admin.d.ts

@@ -6,6 +6,7 @@ declare function CoursesPage(): react.JSX.Element;
 declare function LearnersPage(): react.JSX.Element;
 declare function AssignmentsPage(): react.JSX.Element;
 declare function CommunityPage(): react.JSX.Element;
+declare function PathsPage(): react.JSX.Element;
 declare function CohortsPage(): react.JSX.Element;
 declare function ReportsPage(): react.JSX.Element;
 declare function NotificationsPage(): react.JSX.Element;
@@ -19,6 +20,7 @@ declare const pages: {
   "/assignments": typeof AssignmentsPage;
   "/community": typeof CommunityPage;
   "/cohorts": typeof CohortsPage;
+  "/paths": typeof PathsPage;
   "/reports": typeof ReportsPage;
   "/notifications": typeof NotificationsPage;
   "/audit": typeof AuditPage;
@@ -28,5 +30,5 @@ declare const widgets: {
   learning: typeof LearningWidget;
 };
 //#endregion
-export { AssignmentsPage, AuditPage, CohortsPage, CommunityPage, CoursesPage, LearnersPage, LearningWidget, NotificationsPage, OverviewPage, ReportsPage, SettingsPage, pages, widgets };
+export { AssignmentsPage, AuditPage, CohortsPage, CommunityPage, CoursesPage, LearnersPage, LearningWidget, NotificationsPage, OverviewPage, PathsPage, ReportsPage, SettingsPage, pages, widgets };
 //# sourceMappingURL=admin.d.ts.map