@hydralms/components 0.1.1 → 0.1.3

package/src/questions/multiple-choice.tsx

@@ -0,0 +1,97 @@
+import { useState, useEffect } from "react";
+import type { QuestionProps } from "./types";
+import { Alert, AlertDescription } from "../ui/alert";
+import { cn } from "../lib/utils";
+
+/**
+ * MultipleChoice renders a question with multiple correct answers using checkboxes.
+ *
+ * @example
+ * <MultipleChoice
+ *   question={question}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const MultipleChoice = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) => {
+  const [selectedAnswers, setSelectedAnswers] = useState<string[]>([]);
+
+  const sortedAnswers = [...(question.answers || [])].sort(
+    (a, b) => a.sequence - b.sequence,
+  );
+
+  const handleChange = (uid: string) => {
+    if (readOnly || disabled) return;
+
+    setSelectedAnswers((prev) => {
+      const newSelected = prev.includes(uid)
+        ? prev.filter((id) => id !== uid)
+        : [...prev, uid];
+
+      onAnswer?.(newSelected.map((id) => ({ uid: id })));
+      return newSelected;
+    });
+  };
+
+  useEffect(() => {
+    const current = sessionAnswers?.map((sa) => sa.answerUid) || [];
+    setSelectedAnswers(current);
+  }, [sessionAnswers]);
+
+  const getAnswerClasses = (answerUid: string) => {
+    if (!showCorrectAnswers) return "";
+
+    const answer = question.answers?.find((a) => a.uid === answerUid);
+    if (answer?.isCorrect) {
+      return "bg-success/10 border border-success/30 px-2";
+    }
+    if (selectedAnswers.includes(answerUid) && !answer?.isCorrect) {
+      return "bg-destructive/10 border border-destructive/30 px-2";
+    }
+    return "";
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+
+      <div className="flex flex-col gap-2">
+        {sortedAnswers.map((answer) => (
+          <div
+            key={answer.uid}
+            className={cn("rounded-md transition-colors", getAnswerClasses(answer.uid))}
+          >
+            <label className="flex items-center gap-2 cursor-pointer py-1 has-[input:disabled]:cursor-default has-[input:disabled]:opacity-60">
+              <input
+                type="checkbox"
+                checked={selectedAnswers.includes(answer.uid)}
+                onChange={() => handleChange(answer.uid)}
+                disabled={readOnly || disabled}
+                className="accent-primary m-0 shrink-0"
+              />
+              <span
+                className="text-sm"
+                dangerouslySetInnerHTML={{ __html: answer.content }}
+              />
+            </label>
+          </div>
+        ))}
+      </div>
+
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-2">
+          <AlertDescription>
+            <strong>Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+};

package/src/questions/question-renderer.tsx

@@ -0,0 +1,37 @@
+import type { QuestionProps } from "./types";
+import { MultipleChoice } from "./multiple-choice";
+import { Choice } from "./choice";
+import { TrueFalse } from "./true-false";
+import { FillInTheBlank } from "./fill-in-the-blank";
+import { Essay } from "./essay";
+
+/**
+ * QuestionRenderer dispatches to the appropriate question component based on question type.
+ *
+ * @example
+ * <QuestionRenderer
+ *   question={question}
+ *   sessionAnswers={answers}
+ *   onAnswer={handleAnswer}
+ * />
+ */
+export const QuestionRenderer = (props: QuestionProps) => {
+  switch (props.question.type) {
+    case "multiple_choice":
+      return <MultipleChoice {...props} />;
+    case "choice":
+      return <Choice {...props} />;
+    case "true_false":
+      return <TrueFalse {...props} />;
+    case "fill_in_the_blank":
+      return <FillInTheBlank {...props} />;
+    case "essay":
+      return <Essay {...props} />;
+    default:
+      return (
+        <p className="text-muted-foreground">
+          Question type &ldquo;{props.question.type}&rdquo; is not supported yet.
+        </p>
+      );
+  }
+};

package/src/questions/true-false.test.tsx

@@ -0,0 +1,89 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { TrueFalse } from "./true-false";
+import type { QuestionData } from "./types";
+
+const mockQuestion: QuestionData = {
+  uid: "q1",
+  type: "true_false",
+  content: "<p>The sky is blue.</p>",
+  explanation: "<p>Due to Rayleigh scattering.</p>",
+  answers: [
+    { uid: "a1", content: "True", isCorrect: true, sequence: 1 },
+    { uid: "a2", content: "False", isCorrect: false, sequence: 2 },
+  ],
+};
+
+describe("TrueFalse", () => {
+  it("renders question content and both options", () => {
+    render(<TrueFalse question={mockQuestion} />);
+    expect(screen.getByText("The sky is blue.")).toBeInTheDocument();
+    expect(screen.getByText("True")).toBeInTheDocument();
+    expect(screen.getByText("False")).toBeInTheDocument();
+  });
+
+  it("renders radio inputs", () => {
+    render(<TrueFalse question={mockQuestion} />);
+    const radios = screen.getAllByRole("radio");
+    expect(radios).toHaveLength(2);
+  });
+
+  it("calls onAnswer when an option is selected", async () => {
+    const onAnswer = vi.fn();
+    const user = userEvent.setup();
+
+    render(<TrueFalse question={mockQuestion} onAnswer={onAnswer} />);
+    await user.click(screen.getByText("True"));
+
+    expect(onAnswer).toHaveBeenCalledWith([{ uid: "a1" }]);
+  });
+
+  it("disables inputs when readOnly is true", () => {
+    render(<TrueFalse question={mockQuestion} readOnly />);
+    const radios = screen.getAllByRole("radio");
+    radios.forEach((radio) => expect(radio).toBeDisabled());
+  });
+
+  it("disables inputs when disabled is true", () => {
+    render(<TrueFalse question={mockQuestion} disabled />);
+    const radios = screen.getAllByRole("radio");
+    radios.forEach((radio) => expect(radio).toBeDisabled());
+  });
+
+  it("shows explanation when showCorrectAnswers is true", () => {
+    render(<TrueFalse question={mockQuestion} showCorrectAnswers />);
+    expect(screen.getByText("Explanation:")).toBeInTheDocument();
+    expect(screen.getByText("Due to Rayleigh scattering.")).toBeInTheDocument();
+  });
+
+  it("does not show explanation when showCorrectAnswers is false", () => {
+    render(<TrueFalse question={mockQuestion} showCorrectAnswers={false} />);
+    expect(screen.queryByText("Explanation:")).not.toBeInTheDocument();
+  });
+
+  it("pre-selects answer from sessionAnswers", () => {
+    render(
+      <TrueFalse
+        question={mockQuestion}
+        sessionAnswers={[{ uid: "sa1", answerUid: "a1" }]}
+      />,
+    );
+    const radios = screen.getAllByRole("radio");
+    expect(radios[0]).toBeChecked();
+  });
+
+  it("sorts answers by sequence", () => {
+    const reversed: QuestionData = {
+      ...mockQuestion,
+      answers: [
+        { uid: "a2", content: "False", isCorrect: false, sequence: 2 },
+        { uid: "a1", content: "True", isCorrect: true, sequence: 1 },
+      ],
+    };
+
+    render(<TrueFalse question={reversed} />);
+    const radios = screen.getAllByRole("radio");
+    const labels = radios.map((r) => r.closest("label")?.textContent);
+    expect(labels).toEqual(["True", "False"]);
+  });
+});

package/src/questions/true-false.tsx

@@ -0,0 +1,90 @@
+import { useState, useEffect } from "react";
+import type { QuestionProps } from "./types";
+import { Alert, AlertDescription } from "../ui/alert";
+import { cn } from "../lib/utils";
+
+/**
+ * TrueFalse renders a true/false question with two radio button options.
+ *
+ * @example
+ * <TrueFalse
+ *   question={question}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const TrueFalse = ({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) => {
+  const [selectedAnswer, setSelectedAnswer] = useState<string>("");
+
+  const sortedAnswers = [...(question.answers || [])].sort(
+    (a, b) => a.sequence - b.sequence,
+  );
+
+  const handleChange = (uid: string) => {
+    if (readOnly || disabled) return;
+
+    setSelectedAnswer(uid);
+    onAnswer?.([{ uid }]);
+  };
+
+  useEffect(() => {
+    const current = sessionAnswers?.[0]?.answerUid || "";
+    setSelectedAnswer(current);
+  }, [sessionAnswers]);
+
+  const getAnswerClasses = (answerUid: string) => {
+    if (!showCorrectAnswers) return "px-2";
+
+    const answer = question.answers?.find((a) => a.uid === answerUid);
+    if (answer?.isCorrect) {
+      return "bg-success/10 border border-success/30 px-2";
+    }
+    if (selectedAnswer === answerUid && !answer?.isCorrect) {
+      return "bg-destructive/10 border border-destructive/30 px-2";
+    }
+    return "px-2";
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+
+      <div className="flex flex-col gap-2">
+        {sortedAnswers.map((answer) => (
+          <div
+            key={answer.uid}
+            className={cn("rounded-md transition-colors", getAnswerClasses(answer.uid))}
+          >
+            <label className="flex items-center gap-2 cursor-pointer py-1 has-[input:disabled]:cursor-default has-[input:disabled]:opacity-60">
+              <input
+                type="radio"
+                name={question.uid}
+                value={answer.uid}
+                checked={selectedAnswer === answer.uid}
+                onChange={() => handleChange(answer.uid)}
+                disabled={readOnly || disabled}
+                className="accent-primary m-0 shrink-0"
+              />
+              <span dangerouslySetInnerHTML={{ __html: answer.content }} />
+            </label>
+          </div>
+        ))}
+      </div>
+
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-2">
+          <AlertDescription>
+            <strong>Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+};

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