@hydralms/components 0.1.1 → 0.1.3

package/src/sections/CourseOutline/CourseOutline.tsx

@@ -0,0 +1,79 @@
+import { useMemo } from "react";
+import { CurriculumTree } from "../../curriculum";
+import type { CurriculumItem } from "../../curriculum/types";
+import { Progress } from "../../ui/progress";
+import type { CourseOutlineProps } from "./types";
+import { cn } from "../../lib/utils";
+
+function flattenLeaves(items: CurriculumItem[]): string[] {
+  const leaves: string[] = [];
+  for (const item of items) {
+    if (!item.children || item.children.length === 0) {
+      leaves.push(item.uid);
+    } else {
+      leaves.push(...flattenLeaves(item.children));
+    }
+  }
+  return leaves;
+}
+
+export function CourseOutline({
+  items,
+  progress,
+  courseTitle,
+  activeItemUid,
+  onItemClick,
+  showOverallProgress = true,
+  showDuration = true,
+  showIcons = true,
+  readOnly = false,
+  className,
+  style,
+}: CourseOutlineProps) {
+  const { completedCount, totalCount, percentage } = useMemo(() => {
+    const leafUids = flattenLeaves(items);
+    const total = leafUids.length;
+    const completed = progress
+      ? leafUids.filter((uid) =>
+          progress.some((p) => p.resourceUid === uid && p.isCompleted),
+        ).length
+      : 0;
+    return {
+      completedCount: completed,
+      totalCount: total,
+      percentage: total > 0 ? Math.round((completed / total) * 100) : 0,
+    };
+  }, [items, progress]);
+
+  return (
+    <div className={cn(className)} style={style}>
+      {(courseTitle || showOverallProgress) && (
+        <div className="px-2 pt-2 pb-1">
+          {courseTitle && (
+            <p className={cn("font-semibold text-sm text-foreground", showOverallProgress && "mb-1")}>
+              {courseTitle}
+            </p>
+          )}
+          {showOverallProgress && (
+            <div>
+              <Progress value={percentage} size="sm" />
+              <span className="text-xs text-muted-foreground mt-0.5 block">
+                {completedCount} of {totalCount} completed
+              </span>
+            </div>
+          )}
+        </div>
+      )}
+      <CurriculumTree
+        items={items}
+        progress={progress}
+        activeItemUid={activeItemUid}
+        onItemClick={onItemClick}
+        readOnly={readOnly}
+        showDuration={showDuration}
+        showIcons={showIcons}
+        showProgress
+      />
+    </div>
+  );
+}

package/src/sections/CourseOutline/types.ts

@@ -0,0 +1,53 @@
+import type {
+  CurriculumItem,
+  CurriculumItemProgress,
+} from "../../curriculum/types";
+
+/**
+ * CourseOutline section — a sidebar-ready course navigation panel.
+ *
+ * Wraps CurriculumTree with a course title header and an optional overall
+ * progress bar. Ready to drop into a sidebar layout without extra markup.
+ *
+ * @example
+ * <CourseOutline
+ *   items={curriculum}
+ *   progress={userProgress}
+ *   courseTitle="Introduction to React"
+ *   activeItemUid={currentLessonUid}
+ *   onItemClick={(item) => navigate(item.uid)}
+ * />
+ */
+export interface CourseOutlineProps {
+  /** The course curriculum items */
+  items: CurriculumItem[];
+  /** User progress data */
+  progress?: CurriculumItemProgress[];
+  /** Course title displayed in the header */
+  courseTitle?: string;
+  /** UID of the currently active/playing item */
+  activeItemUid?: string;
+  /** Called when the user clicks a leaf curriculum item */
+  onItemClick?: (item: CurriculumItem) => void;
+  /**
+   * Whether to show a linear progress bar summarising overall completion.
+   * @default true
+   */
+  showOverallProgress?: boolean;
+  /**
+   * Whether to show per-item duration labels in the tree.
+   * @default true
+   */
+  showDuration?: boolean;
+  /**
+   * Whether to show type icons per item.
+   * @default true
+   */
+  showIcons?: boolean;
+  /** When true, disables all click interactions */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}

package/src/sections/DiscussionThread/DiscussionThread.tsx

@@ -0,0 +1,186 @@
+import { useMemo, useState } from "react";
+import { CheckCircle, Heart, MessageSquare, Reply } from "lucide-react";
+import { PostCard } from "../../social";
+import { Button } from "../../ui/button";
+import { Textarea } from "../../ui/textarea";
+import { Separator } from "../../ui/separator";
+import { Card, CardContent } from "../../ui/card";
+import { Tooltip, TooltipTrigger, TooltipContent } from "../../ui/tooltip";
+import type { DiscussionThreadProps, DiscussionPost } from "./types";
+import { cn } from "../../lib/utils";
+
+export function DiscussionThread({
+  title,
+  rootPost,
+  replies,
+  currentUser,
+  onReply,
+  onToggleLike,
+  onMarkAnswer,
+  maxDepth = 3,
+  allowReplies = true,
+  sortOrder = "oldest",
+  readOnly = false,
+  className,
+  style,
+}: DiscussionThreadProps) {
+  const [replyingToUid, setReplyingToUid] = useState<string | null>(null);
+  const [replyContent, setReplyContent] = useState("");
+
+  const replyTree = useMemo(() => {
+    const childrenMap = new Map<string, DiscussionPost[]>();
+    for (const reply of replies) {
+      const parentUid = reply.parentUid ?? rootPost.uid;
+      const siblings = childrenMap.get(parentUid) ?? [];
+      siblings.push(reply);
+      childrenMap.set(parentUid, siblings);
+    }
+
+    for (const [, children] of childrenMap) {
+      children.sort((a, b) => {
+        if (sortOrder === "newest") return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
+        if (sortOrder === "most_liked") return b.likeCount - a.likeCount;
+        return new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime();
+      });
+    }
+
+    return childrenMap;
+  }, [replies, rootPost.uid, sortOrder]);
+
+  function handleSubmitReply(parentUid: string) {
+    if (!replyContent.trim()) return;
+    onReply(parentUid, replyContent.trim());
+    setReplyContent("");
+    setReplyingToUid(null);
+  }
+
+  function renderPost(post: DiscussionPost, depth: number) {
+    const children = replyTree.get(post.uid) ?? [];
+    const effectiveDepth = Math.min(depth, maxDepth);
+
+    const actions = (
+      <div className="flex items-center gap-1">
+        {onToggleLike && !readOnly && (
+          <Tooltip>
+            <TooltipTrigger>
+              <Button
+                variant="ghost"
+                size="sm"
+                aria-label={post.isLikedByCurrentUser ? "Unlike" : "Like"}
+                className={cn(post.isLikedByCurrentUser && "text-destructive")}
+                onClick={() => onToggleLike(post.uid)}
+              >
+                <Heart size={14} fill={post.isLikedByCurrentUser ? "currentColor" : "none"} />
+                {post.likeCount > 0 ? post.likeCount : "Like"}
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>{post.isLikedByCurrentUser ? "Unlike" : "Like"}</TooltipContent>
+          </Tooltip>
+        )}
+        {allowReplies && !readOnly && (
+          <Tooltip>
+            <TooltipTrigger>
+              <Button
+                variant="ghost"
+                size="sm"
+                aria-label="Reply"
+                onClick={() => setReplyingToUid(post.uid)}
+              >
+                <Reply size={14} />
+                Reply
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>Reply</TooltipContent>
+          </Tooltip>
+        )}
+        {onMarkAnswer && !readOnly && currentUser.role !== "student" && !post.isAnswer && (
+          <Tooltip>
+            <TooltipTrigger>
+              <Button
+                variant="ghost"
+                size="sm"
+                aria-label="Mark as answer"
+                className="text-success"
+                onClick={() => onMarkAnswer(post.uid)}
+              >
+                <CheckCircle size={14} />
+                Mark Answer
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent>Mark as answer</TooltipContent>
+          </Tooltip>
+        )}
+      </div>
+    );
+
+    return (
+      <div key={post.uid}>
+        <PostCard
+          author={post.author}
+          content={post.content}
+          createdAt={post.createdAt}
+          updatedAt={post.updatedAt}
+          actions={actions}
+          highlight={post.isAnswer ? "answer" : "none"}
+          indentLevel={effectiveDepth}
+          className="mb-2"
+        />
+
+        {/* Reply editor */}
+        {replyingToUid === post.uid && (
+          <Card
+            className="mb-2"
+            style={{ marginLeft: `${(effectiveDepth + 1) * 16}px` }}
+          >
+            <CardContent className="pt-4 pb-4">
+              <Textarea
+                className="min-h-15 mb-2"
+                placeholder="Write a reply..."
+                value={replyContent}
+                onChange={(e) => setReplyContent(e.target.value)}
+              />
+              <div className="flex items-center gap-2">
+                <Button
+                  size="sm"
+                  onClick={() => handleSubmitReply(post.uid)}
+                  disabled={!replyContent.trim()}
+                >
+                  Post Reply
+                </Button>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onClick={() => {
+                    setReplyingToUid(null);
+                    setReplyContent("");
+                  }}
+                >
+                  Cancel
+                </Button>
+              </div>
+            </CardContent>
+          </Card>
+        )}
+
+        {/* Nested children */}
+        {children.map((child) => renderPost(child, depth + 1))}
+      </div>
+    );
+  }
+
+  return (
+    <div className={className} style={style}>
+      <div className="flex items-center gap-1 mb-2">
+        <MessageSquare size={20} className="text-foreground shrink-0" />
+        <span className="text-lg font-semibold text-foreground">{title}</span>
+        <span className="text-sm text-muted-foreground">
+          {replies.length} {replies.length === 1 ? "reply" : "replies"}
+        </span>
+      </div>
+
+      <Separator className="mb-2" />
+
+      {renderPost(rootPost, 0)}
+    </div>
+  );
+}

package/src/sections/DiscussionThread/types.ts

@@ -0,0 +1,77 @@
+
+/**
+ * DiscussionThread section — a threaded discussion forum.
+ *
+ * Supports nested replies, author avatars, timestamps, like/unlike,
+ * and mark-as-answer for Q&A threads. Replies nest up to a
+ * configurable maximum depth.
+ *
+ * @example
+ * <DiscussionThread
+ *   title="How do React hooks work?"
+ *   rootPost={rootPost}
+ *   replies={replies}
+ *   currentUser={user}
+ *   onReply={(parentUid, content) => postReply(parentUid, content)}
+ * />
+ */
+export interface DiscussionThreadProps {
+  /** Thread title */
+  title: string;
+  /** The initial/root post */
+  rootPost: DiscussionPost;
+  /** All replies (flat array — parentUid determines nesting) */
+  replies: DiscussionPost[];
+  /** The currently authenticated user */
+  currentUser: DiscussionUser;
+  /** Called when the user submits a reply */
+  onReply: (parentUid: string, content: string) => void;
+  /** Called when the user toggles a like */
+  onToggleLike?: (postUid: string) => void;
+  /** Called when an instructor marks a post as the answer */
+  onMarkAnswer?: (postUid: string) => void;
+  /** Maximum nesting depth before replies flatten */
+  maxDepth?: number;
+  /** Whether new replies are allowed */
+  allowReplies?: boolean;
+  /** Sort order for top-level replies */
+  sortOrder?: "newest" | "oldest" | "most_liked";
+  /** When true, disables interactions */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface DiscussionPost {
+  /** Unique identifier */
+  uid: string;
+  /** Parent post UID — null for root post */
+  parentUid: string | null;
+  /** Post author */
+  author: DiscussionUser;
+  /** Post body content */
+  content: string;
+  /** Creation timestamp */
+  createdAt: string;
+  /** Last update timestamp */
+  updatedAt?: string;
+  /** Number of likes */
+  likeCount: number;
+  /** Whether the current user has liked this post */
+  isLikedByCurrentUser: boolean;
+  /** Whether this post is marked as the answer */
+  isAnswer?: boolean;
+}
+
+export interface DiscussionUser {
+  /** Unique identifier */
+  uid: string;
+  /** Display name */
+  displayName: string;
+  /** Avatar image URL */
+  avatarUrl?: string;
+  /** User role */
+  role?: "student" | "instructor" | "ta" | "admin";
+}

package/src/sections/ExamSession/ExamSession.tsx

@@ -0,0 +1,182 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+import { AssessmentToolbar } from "../../assessment-toolbar";
+import type { QuestionNavigatorItem } from "../../assessment-toolbar/types";
+import { QuestionRenderer } from "../../questions";
+import type { SessionAnswer } from "../../questions/types";
+import { ConfirmDialog } from "../../common";
+import { Alert, AlertDescription } from "../../ui/alert";
+import { Card, CardContent } from "../../ui/card";
+import { cn } from "../../lib/utils";
+import type { ExamSessionProps, ExamSubmitMetadata } from "./types";
+
+export function ExamSession({
+  questions,
+  initialAnswers = [],
+  onSubmit,
+  onAnswerChange,
+  timeLimitSeconds,
+  timeElapsedSeconds,
+  autoSubmitOnTimeout = true,
+  timeWarningThreshold = 300,
+  allowBackNavigation = true,
+  confirmBeforeSubmit = true,
+  examTitle,
+  instructions,
+  isSubmitting = false,
+  readOnly = false,
+  className,
+  style,
+}: ExamSessionProps) {
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const [sessionAnswers, setSessionAnswers] = useState<SessionAnswer[]>(initialAnswers);
+  const [flaggedUids, setFlaggedUids] = useState<Set<string>>(new Set());
+  const [showConfirm, setShowConfirm] = useState(false);
+  const [showTimeWarning, setShowTimeWarning] = useState(false);
+  const hasAutoSubmitted = useRef(false);
+
+  const currentQuestion = questions[currentIndex];
+  const remainingSeconds = timeLimitSeconds - timeElapsedSeconds;
+
+  useEffect(() => {
+    if (remainingSeconds <= timeWarningThreshold && remainingSeconds > 0) {
+      setShowTimeWarning(true);
+    }
+  }, [remainingSeconds, timeWarningThreshold]);
+
+  useEffect(() => {
+    if (autoSubmitOnTimeout && remainingSeconds <= 0 && !hasAutoSubmitted.current) {
+      hasAutoSubmitted.current = true;
+      doSubmit(true);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [remainingSeconds, autoSubmitOnTimeout]);
+
+  const navigatorItems = useMemo<QuestionNavigatorItem[]>(
+    () =>
+      questions.map((q, idx) => ({
+        uid: q.uid,
+        sequence: idx + 1,
+        isFlagged: flaggedUids.has(q.uid),
+        isAnswered: sessionAnswers.some((a) => a.uid === q.uid),
+        isSkipped: false,
+      })),
+    [questions, sessionAnswers, flaggedUids],
+  );
+
+  function handleAnswer(rawAnswers: { uid: string; content?: string }[]) {
+    if (!currentQuestion) return;
+    const questionUid = currentQuestion.uid;
+    const newAnswers: SessionAnswer[] = rawAnswers.map((a) => ({
+      uid: questionUid,
+      answerUid: a.uid,
+      content: a.content,
+    }));
+    setSessionAnswers((prev) => {
+      const filtered = prev.filter((a) => a.uid !== questionUid);
+      const merged = [...filtered, ...newAnswers];
+      onAnswerChange?.(merged);
+      return merged;
+    });
+  }
+
+  function handleNavigate(uid: string) {
+    const idx = questions.findIndex((q) => q.uid === uid);
+    if (idx !== -1) setCurrentIndex(idx);
+  }
+
+  function handleToggleFlag(uid: string) {
+    setFlaggedUids((prev) => {
+      const next = new Set(prev);
+      if (next.has(uid)) next.delete(uid);
+      else next.add(uid);
+      return next;
+    });
+  }
+
+  function handleSubmitClick() {
+    if (confirmBeforeSubmit) {
+      setShowConfirm(true);
+    } else {
+      doSubmit(false);
+    }
+  }
+
+  function doSubmit(wasAutoSubmitted: boolean) {
+    const answeredUids = new Set(sessionAnswers.map((a) => a.uid));
+    const metadata: ExamSubmitMetadata = {
+      timeElapsedSeconds,
+      wasAutoSubmitted,
+      answeredCount: questions.filter((q) => answeredUids.has(q.uid)).length,
+      totalQuestions: questions.length,
+    };
+    onSubmit(sessionAnswers, metadata);
+  }
+
+  return (
+    <div className={cn(className)} style={style}>
+      {examTitle && (
+        <p className="text-xl font-bold mb-2 text-foreground">{examTitle}</p>
+      )}
+
+      {showTimeWarning && remainingSeconds > 0 && remainingSeconds <= timeWarningThreshold && (
+        <Alert variant="warning" className="mb-2">
+          <AlertDescription>
+            {Math.ceil(remainingSeconds / 60)} minute{Math.ceil(remainingSeconds / 60) !== 1 ? "s" : ""} remaining
+          </AlertDescription>
+        </Alert>
+      )}
+
+      <AssessmentToolbar
+        currentQuestionIndex={currentIndex}
+        totalQuestions={questions.length}
+        hasNext={currentIndex < questions.length - 1}
+        hasPrevious={allowBackNavigation && currentIndex > 0}
+        onNext={() => setCurrentIndex((i) => Math.min(i + 1, questions.length - 1))}
+        onPrevious={() => allowBackNavigation && setCurrentIndex((i) => Math.max(i - 1, 0))}
+        onSubmit={handleSubmitClick}
+        timeElapsedSeconds={timeElapsedSeconds}
+        timeLimitSeconds={timeLimitSeconds}
+        questions={navigatorItems}
+        onNavigateToQuestion={handleNavigate}
+        onToggleFlag={handleToggleFlag}
+        currentQuestionUid={currentQuestion?.uid}
+        isSubmitting={isSubmitting}
+        readOnly={readOnly}
+      />
+
+      {instructions && currentIndex === 0 && (
+        <Card className="mt-3">
+          <CardContent className="pt-6">{instructions}</CardContent>
+        </Card>
+      )}
+
+      {currentQuestion && (
+        <Card className="mt-3">
+          <CardContent className="pt-6">
+            <QuestionRenderer
+              question={currentQuestion}
+              sessionAnswers={sessionAnswers.filter((a) => a.uid === currentQuestion.uid)}
+              onAnswer={handleAnswer}
+              readOnly={readOnly}
+            />
+          </CardContent>
+        </Card>
+      )}
+
+      <ConfirmDialog
+        open={showConfirm}
+        title="Submit Exam?"
+        message={`You have answered ${navigatorItems.filter((q) => q.isAnswered).length} of ${questions.length} questions. Once submitted, you cannot change your answers.`}
+        confirmLabel="Submit Exam"
+        cancelLabel="Continue Exam"
+        confirmColor="primary"
+        onConfirm={() => {
+          setShowConfirm(false);
+          doSubmit(false);
+        }}
+        onCancel={() => setShowConfirm(false)}
+        isLoading={isSubmitting}
+      />
+    </div>
+  );
+}

package/src/sections/ExamSession/types.ts

@@ -0,0 +1,64 @@
+import type { ReactNode } from "react";
+import type { QuestionData, SessionAnswer } from "../../questions/types";
+
+/**
+ * ExamSession section — a formal timed exam experience.
+ *
+ * Provides enforced time limits with auto-submit on timeout, time warnings,
+ * optional back-navigation restriction, and a confirmation dialog before
+ * final submission.
+ *
+ * @example
+ * <ExamSession
+ *   questions={questions}
+ *   timeLimitSeconds={3600}
+ *   timeElapsedSeconds={elapsed}
+ *   onSubmit={(answers, meta) => submitExam(answers, meta)}
+ *   examTitle="Final Exam"
+ * />
+ */
+export interface ExamSessionProps {
+  /** Ordered list of questions */
+  questions: QuestionData[];
+  /** Pre-populated answers for resuming */
+  initialAnswers?: SessionAnswer[];
+  /** Called on submission with answers and metadata */
+  onSubmit: (answers: SessionAnswer[], metadata: ExamSubmitMetadata) => void;
+  /** Called whenever the user changes an answer */
+  onAnswerChange?: (answers: SessionAnswer[]) => void;
+  /** Time limit in seconds (required for exam mode) */
+  timeLimitSeconds: number;
+  /** Current elapsed time in seconds (controlled externally) */
+  timeElapsedSeconds: number;
+  /** Auto-submit when time runs out */
+  autoSubmitOnTimeout?: boolean;
+  /** Seconds remaining at which to show a time warning */
+  timeWarningThreshold?: number;
+  /** Whether the user can go back to previous questions */
+  allowBackNavigation?: boolean;
+  /** Show a confirmation dialog before final submission */
+  confirmBeforeSubmit?: boolean;
+  /** Title shown in the exam header */
+  examTitle?: string;
+  /** Instructions displayed above the first question */
+  instructions?: ReactNode;
+  /** Whether the submit action is in flight */
+  isSubmitting?: boolean;
+  /** When true, all inputs are disabled */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface ExamSubmitMetadata {
+  /** Total time the user spent in seconds */
+  timeElapsedSeconds: number;
+  /** Whether the submission was triggered by timeout */
+  wasAutoSubmitted: boolean;
+  /** Number of questions the user answered */
+  answeredCount: number;
+  /** Total questions in the exam */
+  totalQuestions: number;
+}