@hydralms/components 0.1.0 → 0.1.2

package/src/questions/types.ts

@@ -0,0 +1,53 @@
+export type QuestionTypeEnum =
+  | "multiple_choice"
+  | "choice"
+  | "true_false"
+  | "fill_in_the_blank"
+  | "essay";
+
+export interface AnswerOption {
+  uid: string;
+  content: string;
+  explanation?: string;
+  isCorrect?: boolean;
+  sequence: number;
+}
+
+export interface SessionAnswer {
+  uid: string;
+  answerUid: string;
+  content?: string;
+  confidence?: string;
+}
+
+export interface QuestionData {
+  uid: string;
+  type: QuestionTypeEnum;
+  content: string;
+  explanation?: string;
+  answers?: AnswerOption[];
+}
+
+/**
+ * Shared props interface for all question type components.
+ *
+ * @example
+ * <QuestionRenderer
+ *   question={{ uid: "q1", type: "choice", content: "What is JSX?", answers: [...] }}
+ *   onAnswer={(answers) => saveAnswer(answers)}
+ * />
+ */
+export interface QuestionProps {
+  /** The question data to render */
+  question: QuestionData;
+  /** Current user answers for this question */
+  sessionAnswers?: SessionAnswer[];
+  /** Called when the user selects or changes an answer */
+  onAnswer?: (answers: { uid: string; content?: string }[]) => void;
+  /** When true, disables all input interactions */
+  readOnly?: boolean;
+  /** When true, highlights correct/incorrect answers */
+  showCorrectAnswers?: boolean;
+  /** When true, disables inputs without showing review state */
+  disabled?: boolean;
+}

package/src/sections/AnnouncementFeed/AnnouncementFeed.tsx

@@ -0,0 +1,141 @@
+import { useMemo, useState } from "react";
+import { Pin } from "lucide-react";
+import { UserAvatar } from "../../social";
+import { EmptyState } from "../../common";
+import { Badge } from "../../ui/badge";
+import { Button } from "../../ui/button";
+import { Card, CardContent } from "../../ui/card";
+import type { AnnouncementFeedProps } from "./types";
+import { cn } from "../../lib/utils";
+
+function formatTimestamp(iso: string): string {
+  const date = new Date(iso);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 60000);
+  if (diffMins < 1) return "Just now";
+  if (diffMins < 60) return `${diffMins}m ago`;
+  const diffHours = Math.floor(diffMins / 60);
+  if (diffHours < 24) return `${diffHours}h ago`;
+  const diffDays = Math.floor(diffHours / 24);
+  if (diffDays < 7) return `${diffDays}d ago`;
+  return date.toLocaleDateString();
+}
+
+export function AnnouncementFeed({
+  announcements,
+  onMarkRead,
+  onSelect,
+  showAvatars = true,
+  previewLines = 3,
+  emptyMessage = "No announcements yet",
+  readOnly = false,
+  className,
+  style,
+}: AnnouncementFeedProps) {
+  const [expandedUids, setExpandedUids] = useState<Set<string>>(new Set());
+
+  const sorted = useMemo(() => {
+    const pinned = announcements.filter((a) => a.isPinned);
+    const rest = announcements.filter((a) => !a.isPinned);
+    return [...pinned, ...rest];
+  }, [announcements]);
+
+  function toggleExpand(uid: string) {
+    setExpandedUids((prev) => {
+      const next = new Set(prev);
+      if (next.has(uid)) next.delete(uid);
+      else next.add(uid);
+      return next;
+    });
+    const announcement = announcements.find((a) => a.uid === uid);
+    if (announcement && !announcement.isRead) {
+      onMarkRead?.(uid);
+    }
+  }
+
+  if (sorted.length === 0) {
+    return (
+      <div className={className} style={style}>
+        <EmptyState title={emptyMessage} />
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("flex flex-col gap-2", className)} style={style}>
+      {sorted.map((a) => {
+        const isExpanded = expandedUids.has(a.uid);
+
+        return (
+          <Card
+            key={a.uid}
+            className={cn(
+              a.isRead && "opacity-85",
+              onSelect && "cursor-pointer",
+              a.isPinned && "border-l-4 border-l-warning",
+            )}
+            onClick={() => onSelect && !readOnly ? onSelect(a) : toggleExpand(a.uid)}
+          >
+            <CardContent className="pt-4 pb-4">
+              <div className="flex gap-1.5 items-start">
+                {showAvatars && (
+                  <UserAvatar
+                    displayName={a.author.displayName}
+                    avatarUrl={a.author.avatarUrl}
+                    role={a.author.role as "student" | "instructor" | "ta" | "admin" | undefined}
+                    size="medium"
+                  />
+                )}
+                <div className="flex-1 min-w-0">
+                  <div className="flex items-center gap-1 mb-0.5">
+                    {a.isPinned && <Pin size={14} />}
+                    <span
+                      className={cn("text-foreground", !a.isRead ? "font-semibold" : "font-normal")}
+                    >
+                      {a.title}
+                    </span>
+                    {!a.isRead && (
+                      <Badge variant="destructive" className="text-[10px] px-1.5 py-0">
+                        New
+                      </Badge>
+                    )}
+                  </div>
+                  <span className="block text-xs text-muted-foreground mb-1">
+                    {a.author.displayName} · {formatTimestamp(a.createdAt)}
+                  </span>
+                  <span
+                    className={cn(
+                      "text-sm text-foreground",
+                      !isExpanded && "line-clamp-(--preview-lines) overflow-hidden",
+                    )}
+                    style={
+                      !isExpanded
+                        ? { "--preview-lines": previewLines } as React.CSSProperties
+                        : undefined
+                    }
+                  >
+                    {a.content}
+                  </span>
+                  {!isExpanded && a.content.length > 200 && (
+                    <Button
+                      variant="link"
+                      size="xs"
+                      className="px-0 mt-0.5 h-auto"
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        toggleExpand(a.uid);
+                      }}
+                    >
+                      Read more
+                    </Button>
+                  )}
+                </div>
+              </div>
+            </CardContent>
+          </Card>
+        );
+      })}
+    </div>
+  );
+}

package/src/sections/AnnouncementFeed/types.ts

@@ -0,0 +1,50 @@
+
+/**
+ * AnnouncementFeed section — a chronological announcement feed.
+ *
+ * Displays course announcements with pinned posts, read/unread
+ * tracking, expandable content, and author avatars.
+ *
+ * @example
+ * <AnnouncementFeed
+ *   announcements={announcements}
+ *   onMarkRead={(uid) => markRead(uid)}
+ * />
+ */
+export interface AnnouncementFeedProps {
+  /** Announcements sorted by recency (newest first) */
+  announcements: Announcement[];
+  /** Called when the user marks an announcement as read */
+  onMarkRead?: (announcementUid: string) => void;
+  /** Called when the user clicks an announcement */
+  onSelect?: (announcement: Announcement) => void;
+  /** Whether to show author avatars */
+  showAvatars?: boolean;
+  /** Max lines before truncating with "Read more" */
+  previewLines?: number;
+  /** Empty state message */
+  emptyMessage?: string;
+  /** 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 Announcement {
+  /** Unique identifier */
+  uid: string;
+  /** Announcement title */
+  title: string;
+  /** Announcement body content */
+  content: string;
+  /** Author information */
+  author: { displayName: string; avatarUrl?: string; role?: string };
+  /** Creation timestamp as ISO string */
+  createdAt: string;
+  /** Whether this announcement is pinned */
+  isPinned?: boolean;
+  /** Whether the current user has read this */
+  isRead?: boolean;
+}

package/src/sections/AssessmentReview/AssessmentReview.tsx

@@ -0,0 +1,148 @@
+import { QuestionRenderer } from "../../questions";
+import type { QuestionData, SessionAnswer } from "../../questions/types";
+import { Badge } from "../../ui/badge";
+import { Card, CardContent } from "../../ui/card";
+import { Separator } from "../../ui/separator";
+import { cn } from "../../lib/utils";
+import type {
+  AssessmentReviewProps,
+  AssessmentReviewGroup,
+} from "./types";
+
+function ScoreHeader({
+  score,
+}: {
+  score: NonNullable<AssessmentReviewProps["score"]>;
+}) {
+  const pct =
+    score.percentage !== undefined
+      ? score.percentage
+      : score.total > 0
+        ? Math.round((score.correct / score.total) * 100)
+        : 0;
+
+  return (
+    <Card className="mb-3">
+      <CardContent className="pt-6">
+        <div className="flex flex-wrap items-center gap-2">
+          <div>
+            <span className="text-2xl font-bold leading-none text-foreground">{pct}%</span>
+            <span className="text-sm text-muted-foreground">
+              {score.correct} of {score.total} correct
+            </span>
+          </div>
+          {score.passed !== undefined && (
+            <Badge variant={score.passed ? "success" : "destructive"}>
+              {score.passed ? "Passed" : "Failed"}
+            </Badge>
+          )}
+          {score.passingScore !== undefined && (
+            <span className="text-sm text-muted-foreground">
+              Passing score: {score.passingScore}%
+            </span>
+          )}
+        </div>
+      </CardContent>
+    </Card>
+  );
+}
+
+function QuestionList({
+  questions,
+  sessionAnswers,
+  showCorrectAnswers,
+}: {
+  questions: QuestionData[];
+  sessionAnswers: SessionAnswer[];
+  showCorrectAnswers: boolean;
+}) {
+  return (
+    <div className="flex flex-col gap-3">
+      {questions.map((question, idx) => (
+        <Card key={question.uid} className="overflow-hidden">
+          <div className="px-2 py-1 bg-muted">
+            <span className="text-xs text-muted-foreground font-semibold">
+              Question {idx + 1}
+            </span>
+          </div>
+          <Separator />
+          <CardContent className="pt-4 pb-4">
+            <QuestionRenderer
+              question={question}
+              sessionAnswers={sessionAnswers.filter((a) => a.uid === question.uid)}
+              readOnly
+              showCorrectAnswers={showCorrectAnswers}
+            />
+          </CardContent>
+        </Card>
+      ))}
+    </div>
+  );
+}
+
+function renderGroups(
+  questions: QuestionData[],
+  sessionAnswers: SessionAnswer[],
+  questionGroups: AssessmentReviewGroup[],
+  showCorrectAnswers: boolean,
+) {
+  const questionMap = new Map(questions.map((q) => [q.uid, q]));
+  const groupedUids = new Set(questionGroups.flatMap((g) => g.questionUids));
+  const ungrouped = questions.filter((q) => !groupedUids.has(q.uid));
+
+  return (
+    <div className="flex flex-col gap-4">
+      {questionGroups.map((group) => {
+        const groupQuestions = group.questionUids
+          .map((uid) => questionMap.get(uid))
+          .filter(Boolean) as QuestionData[];
+        return (
+          <div key={group.label}>
+            <span className="uppercase text-xs tracking-wide text-muted-foreground font-semibold">
+              {group.label}
+            </span>
+            <Separator className="mb-2" />
+            <QuestionList
+              questions={groupQuestions}
+              sessionAnswers={sessionAnswers}
+              showCorrectAnswers={showCorrectAnswers}
+            />
+          </div>
+        );
+      })}
+      {ungrouped.length > 0 && (
+        <div>
+          <QuestionList
+            questions={ungrouped}
+            sessionAnswers={sessionAnswers}
+            showCorrectAnswers={showCorrectAnswers}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+export function AssessmentReview({
+  questions,
+  sessionAnswers,
+  score,
+  questionGroups,
+  showCorrectAnswers = true,
+  className,
+  style,
+}: AssessmentReviewProps) {
+  return (
+    <div className={cn(className)} style={style}>
+      {score && <ScoreHeader score={score} />}
+      {questionGroups && questionGroups.length > 0
+        ? renderGroups(questions, sessionAnswers, questionGroups, showCorrectAnswers)
+        : <QuestionList
+            questions={questions}
+            sessionAnswers={sessionAnswers}
+            showCorrectAnswers={showCorrectAnswers}
+          />
+      }
+    </div>
+  );
+}

package/src/sections/AssessmentReview/types.ts

@@ -0,0 +1,61 @@
+import type { QuestionData, SessionAnswer } from "../../questions/types";
+
+/**
+ * AssessmentReview section — read-only review of a completed assessment.
+ *
+ * Renders all questions in review mode with correct/incorrect highlighting
+ * and an optional score summary header. Supports optional grouping of
+ * questions by section label.
+ *
+ * @example
+ * <AssessmentReview
+ *   questions={questions}
+ *   sessionAnswers={submittedAnswers}
+ *   score={{ correct: 8, total: 10, passed: true, passingScore: 70 }}
+ * />
+ */
+export interface AssessmentReviewProps {
+  /** All questions that were in the assessment */
+  questions: QuestionData[];
+  /** The user's submitted answers */
+  sessionAnswers: SessionAnswer[];
+  /**
+   * Score metadata to display in the summary header.
+   * If omitted, the score header is not rendered.
+   */
+  score?: AssessmentScore;
+  /**
+   * Optional grouping: renders questions under section headings.
+   * Questions not referenced in any group are rendered last without a heading.
+   */
+  questionGroups?: AssessmentReviewGroup[];
+  /**
+   * Whether to show correct/incorrect answer highlighting on each question.
+   * @default true
+   */
+  showCorrectAnswers?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface AssessmentScore {
+  /** Number of correct answers */
+  correct: number;
+  /** Total number of questions */
+  total: number;
+  /** Optional pre-computed percentage (falls back to correct/total * 100) */
+  percentage?: number;
+  /** Whether the user passed */
+  passed?: boolean;
+  /** Passing threshold as a percentage (e.g. 70 means 70%) */
+  passingScore?: number;
+}
+
+export interface AssessmentReviewGroup {
+  /** Group label displayed as a section heading */
+  label: string;
+  /** UIDs of questions belonging to this group, in display order */
+  questionUids: string[];
+}

package/src/sections/AssignmentSubmission/AssignmentSubmission.tsx

@@ -0,0 +1,190 @@
+import { useState } from "react";
+import { Send, Save } from "lucide-react";
+import { StatusBadge, DueDateDisplay } from "../../common";
+import { FileUploadZone } from "../../content";
+import { Button } from "../../ui/button";
+import { Textarea } from "../../ui/textarea";
+import { Input } from "../../ui/input";
+import { Separator } from "../../ui/separator";
+import { Card, CardContent } from "../../ui/card";
+import { Alert, AlertDescription } from "../../ui/alert";
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "../../ui/tabs";
+import type { AssignmentSubmissionProps, SubmissionData } from "./types";
+
+export function AssignmentSubmission({
+  title,
+  instructions,
+  dueDate,
+  maxScore,
+  status,
+  submissionTypes,
+  existingSubmission,
+  fileConstraints,
+  onSubmit,
+  onSaveDraft,
+  grade,
+  isSubmitting = false,
+  readOnly = false,
+  className,
+  style,
+}: AssignmentSubmissionProps) {
+  const [textContent, setTextContent] = useState(existingSubmission?.textContent ?? "");
+  const [files, setFiles] = useState<File[]>(existingSubmission?.files ?? []);
+  const [url, setUrl] = useState(existingSubmission?.url ?? "");
+  const [activeTab, setActiveTab] = useState<"text" | "file" | "url">(submissionTypes[0]);
+
+  const isEditable = !readOnly && !["submitted", "graded"].includes(status);
+
+  function getSubmissionData(): SubmissionData {
+    return {
+      textContent: submissionTypes.includes("text") ? textContent : undefined,
+      files: submissionTypes.includes("file") ? files : undefined,
+      url: submissionTypes.includes("url") ? url : undefined,
+    };
+  }
+
+  return (
+    <div className={className} style={style}>
+      {/* Header */}
+      <div className="flex justify-between items-start mb-2">
+        <div>
+          <div className="text-xl font-bold text-foreground mb-0.5">{title}</div>
+          <div className="flex items-center gap-2">
+            <StatusBadge status={status} />
+            {dueDate && <DueDateDisplay dueDate={dueDate} size="small" />}
+            {maxScore != null && (
+              <span className="text-sm text-muted-foreground">{maxScore} points</span>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/* Instructions */}
+      <Card className="mb-3">
+        <CardContent className="pt-6">
+          <div className="font-semibold text-sm text-foreground mb-1">Instructions</div>
+          <div className="text-muted-foreground text-sm">
+            {typeof instructions === "string" ? (
+              <span>{instructions}</span>
+            ) : (
+              instructions
+            )}
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Grade display */}
+      {grade && (
+        <Alert variant="success" className="mb-3">
+          <AlertDescription>
+            <div className="font-semibold text-sm mb-1">
+              Grade: {grade.score}{maxScore != null ? ` / ${maxScore}` : ""}
+            </div>
+            {grade.feedback && (
+              <div>{grade.feedback}</div>
+            )}
+          </AlertDescription>
+        </Alert>
+      )}
+
+      {/* Submission area */}
+      {isEditable && (
+        <>
+          {submissionTypes.length > 1 ? (
+            <Tabs value={activeTab} onValueChange={(v) => setActiveTab(v as "text" | "file" | "url")}>
+              <TabsList>
+                {submissionTypes.includes("text") && <TabsTrigger value="text">Text</TabsTrigger>}
+                {submissionTypes.includes("file") && <TabsTrigger value="file">File Upload</TabsTrigger>}
+                {submissionTypes.includes("url") && <TabsTrigger value="url">URL</TabsTrigger>}
+              </TabsList>
+              {submissionTypes.includes("text") && (
+                <TabsContent value="text">
+                  <Textarea
+                    className="min-h-45"
+                    placeholder="Type your submission..."
+                    value={textContent}
+                    onChange={(e) => setTextContent(e.target.value)}
+                  />
+                </TabsContent>
+              )}
+              {submissionTypes.includes("file") && (
+                <TabsContent value="file">
+                  <FileUploadZone
+                    files={files}
+                    onFilesAdded={(newFiles) => setFiles((prev) => [...prev, ...newFiles])}
+                    onFileRemove={(index) => setFiles((prev) => prev.filter((_, i) => i !== index))}
+                    accept={fileConstraints?.acceptedTypes}
+                    maxFiles={fileConstraints?.maxFiles}
+                    maxSizeMB={fileConstraints?.maxSizeMB}
+                  />
+                </TabsContent>
+              )}
+              {submissionTypes.includes("url") && (
+                <TabsContent value="url">
+                  <Input
+                    placeholder="https://..."
+                    value={url}
+                    onChange={(e) => setUrl(e.target.value)}
+                  />
+                </TabsContent>
+              )}
+            </Tabs>
+          ) : (
+            <>
+              {submissionTypes.includes("text") && (
+                <Textarea
+                  className="min-h-45 mb-2"
+                  placeholder="Type your submission..."
+                  value={textContent}
+                  onChange={(e) => setTextContent(e.target.value)}
+                />
+              )}
+              {submissionTypes.includes("file") && (
+                <div className="mb-2">
+                  <FileUploadZone
+                    files={files}
+                    onFilesAdded={(newFiles) => setFiles((prev) => [...prev, ...newFiles])}
+                    onFileRemove={(index) => setFiles((prev) => prev.filter((_, i) => i !== index))}
+                    accept={fileConstraints?.acceptedTypes}
+                    maxFiles={fileConstraints?.maxFiles}
+                    maxSizeMB={fileConstraints?.maxSizeMB}
+                  />
+                </div>
+              )}
+              {submissionTypes.includes("url") && (
+                <Input
+                  className="mb-2"
+                  placeholder="https://..."
+                  value={url}
+                  onChange={(e) => setUrl(e.target.value)}
+                />
+              )}
+            </>
+          )}
+
+          <Separator className="my-2" />
+
+          <div className="flex gap-2 justify-end">
+            {onSaveDraft && (
+              <Button
+                variant="outline"
+                onClick={() => onSaveDraft(getSubmissionData())}
+                disabled={isSubmitting}
+              >
+                <Save size={16} />
+                Save Draft
+              </Button>
+            )}
+            <Button
+              onClick={() => onSubmit(getSubmissionData())}
+              disabled={isSubmitting}
+            >
+              <Send size={16} />
+              {isSubmitting ? "Submitting..." : "Submit"}
+            </Button>
+          </div>
+        </>
+      )}
+    </div>
+  );
+}