@hydralms/components 0.1.0 → 0.1.2

package/src/sections/ScrollableQuiz/types.ts

@@ -0,0 +1,40 @@
+import type { QuestionData, SessionAnswer } from "../../questions/types";
+
+/**
+ * ScrollableQuiz section — all questions on a single scrollable page.
+ *
+ * Renders every question in a vertical list with a sticky sidebar navigator
+ * that highlights the currently visible question. Supports optional question
+ * grouping by section labels.
+ *
+ * @example
+ * <ScrollableQuiz
+ *   questions={questions}
+ *   onSubmit={(answers) => submit(answers)}
+ *   showNavigator
+ * />
+ */
+export interface ScrollableQuizProps {
+  /** Ordered list of questions to present */
+  questions: QuestionData[];
+  /** Pre-populated answers for resuming */
+  initialAnswers?: SessionAnswer[];
+  /** Called when the user clicks Submit with the full answers array */
+  onSubmit: (answers: SessionAnswer[]) => void;
+  /** Called whenever the user changes any answer (useful for auto-save) */
+  onAnswerChange?: (answers: SessionAnswer[]) => void;
+  /** Whether to show the sticky sidebar navigator */
+  showNavigator?: boolean;
+  /** Whether to show question numbers beside each question */
+  showQuestionNumbers?: boolean;
+  /** Optional grouping of questions into labeled sections */
+  questionGroups?: { label: string; questionUids: string[] }[];
+  /** 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;
+}

package/src/sections/SurveyForm/SurveyForm.tsx

@@ -0,0 +1,180 @@
+import { useState, useMemo } from "react";
+import { LikertScale, StarRating } from "../../feedback";
+import { Button } from "../../ui/button";
+import { Card, CardContent } from "../../ui/card";
+import { Progress } from "../../ui/progress";
+import { Textarea } from "../../ui/textarea";
+import type { SurveyFormProps, SurveyAnswer } from "./types";
+
+export function SurveyForm({
+  title,
+  description,
+  questions,
+  initialAnswers = [],
+  onSubmit,
+  onAnswerChange,
+  showProgress = true,
+  requireAll = false,
+  submitLabel = "Submit Survey",
+  isSubmitting = false,
+  readOnly = false,
+  className,
+  style,
+}: SurveyFormProps) {
+  const [answers, setAnswers] = useState<SurveyAnswer[]>(initialAnswers);
+
+  const answeredCount = useMemo(() => {
+    const answered = new Set(answers.map((a) => a.questionUid));
+    return questions.filter((q) => answered.has(q.uid)).length;
+  }, [questions, answers]);
+
+  const canSubmit = !requireAll || answeredCount === questions.length;
+
+  function setAnswer(questionUid: string, value: string | number) {
+    setAnswers((prev) => {
+      const filtered = prev.filter((a) => a.questionUid !== questionUid);
+      const next = [...filtered, { questionUid, value }];
+      onAnswerChange?.(next);
+      return next;
+    });
+  }
+
+  function getAnswer(questionUid: string): SurveyAnswer | undefined {
+    return answers.find((a) => a.questionUid === questionUid);
+  }
+
+  return (
+    <div className={className} style={style}>
+      <p className="text-xl font-bold text-foreground mb-2">{title}</p>
+      {description && (
+        <div className="mb-2 text-muted-foreground text-sm">
+          {typeof description === "string" ? (
+            <span>{description}</span>
+          ) : (
+            description
+          )}
+        </div>
+      )}
+      {showProgress && (
+        <div className="mb-3">
+          <Progress value={(answeredCount / questions.length) * 100} />
+          <span className="block text-xs text-muted-foreground mt-0.5">
+            {answeredCount} of {questions.length} answered
+          </span>
+        </div>
+      )}
+
+      {questions.map((q, index) => {
+        const answer = getAnswer(q.uid);
+        return (
+          <Card key={q.uid} className="mb-2"><CardContent className="pt-6">
+            <p className="font-medium text-foreground mb-2">
+              {index + 1}. {q.content}
+              {q.required && (
+                <span className="text-destructive ml-0.5">*</span>
+              )}
+            </p>
+
+            {q.type === "likert" && (
+              <LikertScale
+                value={answer ? Number(answer.value) : null}
+                onChange={(v) => setAnswer(q.uid, v)}
+                points={q.scalePoints}
+                lowLabel={q.scaleLabels?.low}
+                highLabel={q.scaleLabels?.high}
+                readOnly={readOnly}
+              />
+            )}
+
+            {q.type === "rating" && (
+              <StarRating
+                value={answer ? Number(answer.value) : 0}
+                onChange={(v) => setAnswer(q.uid, v)}
+                readOnly={readOnly}
+              />
+            )}
+
+            {q.type === "open_text" && (
+              <Textarea
+                placeholder="Type your response..."
+                value={(answer?.value as string) ?? ""}
+                onChange={(e) => setAnswer(q.uid, e.target.value)}
+                disabled={readOnly}
+                className="min-h-24"
+              />
+            )}
+
+            {q.type === "choice" && q.answers && (
+              <div className="flex flex-col gap-2">
+                {q.answers.map((opt) => (
+                  <label key={opt.uid} className="flex items-center gap-2 cursor-pointer py-1 text-sm text-foreground has-[input:disabled]:cursor-default has-[input:disabled]:opacity-60">
+                    <input
+                      type="radio"
+                      className="accent-primary m-0 shrink-0"
+                      name={`survey-q-${q.uid}`}
+                      value={opt.uid}
+                      checked={(answer?.value as string) === opt.uid}
+                      onChange={() => setAnswer(q.uid, opt.uid)}
+                      disabled={readOnly}
+                    />
+                    <span>{opt.content}</span>
+                  </label>
+                ))}
+              </div>
+            )}
+
+            {q.type === "multiple_choice" && q.answers && (
+              <div className="flex flex-col gap-2">
+                {q.answers.map((opt) => {
+                  const selected = answers
+                    .filter((a) => a.questionUid === q.uid)
+                    .map((a) => String(a.value));
+                  return (
+                    <label key={opt.uid} className="flex items-center gap-2 cursor-pointer py-1 text-sm text-foreground has-[input:disabled]:cursor-default has-[input:disabled]:opacity-60">
+                      <input
+                        type="checkbox"
+                        className="accent-primary m-0 shrink-0"
+                        checked={selected.includes(opt.uid)}
+                        disabled={readOnly}
+                        onChange={(e) => {
+                          const prev = answers.filter((a) => a.questionUid === q.uid);
+                          let next: SurveyAnswer[];
+                          if (e.target.checked) {
+                            next = [...prev, { questionUid: q.uid, value: opt.uid }];
+                          } else {
+                            next = prev.filter((a) => String(a.value) !== opt.uid);
+                          }
+                          setAnswers((all) => [
+                            ...all.filter((a) => a.questionUid !== q.uid),
+                            ...next,
+                          ]);
+                          onAnswerChange?.([
+                            ...answers.filter((a) => a.questionUid !== q.uid),
+                            ...next,
+                          ]);
+                        }}
+                      />
+                      <span>{opt.content}</span>
+                    </label>
+                  );
+                })}
+              </div>
+            )}
+          </CardContent></Card>
+        );
+      })}
+
+      <div className="flex justify-between items-center mt-3">
+        <span className="text-sm text-muted-foreground">
+          {answeredCount} of {questions.length} answered
+        </span>
+        <Button
+          onClick={() => onSubmit(answers)}
+          disabled={!canSubmit || isSubmitting || readOnly}
+        >
+          {isSubmitting ? "Submitting..." : submitLabel}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/sections/SurveyForm/types.ts

@@ -0,0 +1,69 @@
+import type { ReactNode } from "react";
+import type { AnswerOption } from "../../questions/types";
+
+/**
+ * SurveyForm section — an ungraded survey/feedback form.
+ *
+ * Supports Likert scale, star rating, open-text, single-choice,
+ * and multiple-choice question types. Questions can be displayed
+ * all at once or one at a time.
+ *
+ * @example
+ * <SurveyForm
+ *   title="Course Evaluation"
+ *   questions={surveyQuestions}
+ *   onSubmit={(answers) => submitSurvey(answers)}
+ * />
+ */
+export interface SurveyFormProps {
+  /** Survey title displayed at the top */
+  title: string;
+  /** Optional introductory text or description */
+  description?: ReactNode;
+  /** Survey questions */
+  questions: SurveyQuestion[];
+  /** Pre-populated answers */
+  initialAnswers?: SurveyAnswer[];
+  /** Called on submission with all answers */
+  onSubmit: (answers: SurveyAnswer[]) => void;
+  /** Called whenever any answer changes */
+  onAnswerChange?: (answers: SurveyAnswer[]) => void;
+  /** Whether to show a progress indicator */
+  showProgress?: boolean;
+  /** Whether all questions must be answered before submit */
+  requireAll?: boolean;
+  /** Label for the submit button */
+  submitLabel?: string;
+  /** 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 SurveyQuestion {
+  /** Unique identifier */
+  uid: string;
+  /** Question type */
+  type: "likert" | "rating" | "open_text" | "choice" | "multiple_choice";
+  /** Question text */
+  content: string;
+  /** For likert: labels for scale endpoints */
+  scaleLabels?: { low: string; high: string };
+  /** For likert: number of scale points */
+  scalePoints?: 5 | 7;
+  /** For choice/multiple_choice: answer options */
+  answers?: AnswerOption[];
+  /** Whether this question is required */
+  required?: boolean;
+}
+
+export interface SurveyAnswer {
+  /** Question UID */
+  questionUid: string;
+  /** Answer value — string for text, number for likert/rating, uid for choice */
+  value: string | number;
+}

package/src/sections/index.ts

@@ -0,0 +1,90 @@
+export { QuizSession } from "./QuizSession/QuizSession";
+export type { QuizSessionProps } from "./QuizSession/types";
+
+export { LecturePlayer } from "./LecturePlayer/LecturePlayer";
+export type { LecturePlayerProps } from "./LecturePlayer/types";
+
+export { FlashcardStudySession } from "./FlashcardStudySession/FlashcardStudySession";
+export type {
+  FlashcardStudySessionProps,
+  FlashcardSessionStats,
+} from "./FlashcardStudySession/types";
+
+export { AssessmentReview } from "./AssessmentReview/AssessmentReview";
+export type {
+  AssessmentReviewProps,
+  AssessmentScore,
+  AssessmentReviewGroup,
+} from "./AssessmentReview/types";
+
+export { CourseOutline } from "./CourseOutline/CourseOutline";
+export type { CourseOutlineProps } from "./CourseOutline/types";
+
+export { ScrollableQuiz } from "./ScrollableQuiz/ScrollableQuiz";
+export type { ScrollableQuizProps } from "./ScrollableQuiz/types";
+
+export { PracticeQuiz } from "./PracticeQuiz/PracticeQuiz";
+export type {
+  PracticeQuizProps,
+  PracticeQuizStats,
+} from "./PracticeQuiz/types";
+
+export { ExamSession } from "./ExamSession/ExamSession";
+export type {
+  ExamSessionProps,
+  ExamSubmitMetadata,
+} from "./ExamSession/types";
+
+export { SurveyForm } from "./SurveyForm/SurveyForm";
+export type {
+  SurveyFormProps,
+  SurveyQuestion,
+  SurveyAnswer,
+} from "./SurveyForm/types";
+
+export { LessonPage } from "./LessonPage/LessonPage";
+export type { LessonPageProps } from "./LessonPage/types";
+
+export { ResourceLibrary } from "./ResourceLibrary/ResourceLibrary";
+export type {
+  ResourceLibraryProps,
+  Resource,
+} from "./ResourceLibrary/types";
+
+export { AnnouncementFeed } from "./AnnouncementFeed/AnnouncementFeed";
+export type {
+  AnnouncementFeedProps,
+  Announcement,
+} from "./AnnouncementFeed/types";
+
+export { DiscussionThread } from "./DiscussionThread/DiscussionThread";
+export type {
+  DiscussionThreadProps,
+  DiscussionPost,
+  DiscussionUser,
+} from "./DiscussionThread/types";
+
+export { AssignmentSubmission } from "./AssignmentSubmission/AssignmentSubmission";
+export type {
+  AssignmentSubmissionProps,
+  SubmissionData,
+} from "./AssignmentSubmission/types";
+
+export { GradebookTable } from "./GradebookTable/GradebookTable";
+export type {
+  GradebookTableProps,
+  GradeItem,
+  GradeCategory,
+  OverallGrade,
+} from "./GradebookTable/types";
+
+export { ProgressDashboard } from "./ProgressDashboard/ProgressDashboard";
+export type {
+  ProgressDashboardProps,
+  ModuleProgress,
+  ActivityItem,
+  Achievement,
+} from "./ProgressDashboard/types";
+
+export { CertificateViewer } from "./CertificateViewer/CertificateViewer";
+export type { CertificateViewerProps } from "./CertificateViewer/types";

package/src/social/index.ts

@@ -0,0 +1,3 @@
+export { UserAvatar } from "./user-avatar";
+export { PostCard } from "./post-card";
+export type { UserAvatarProps, PostCardProps } from "./types";

package/src/social/post-card.tsx

@@ -0,0 +1,91 @@
+import { Pin } from "lucide-react";
+import { UserAvatar } from "./user-avatar";
+import { Separator } from "../ui/separator";
+import type { PostCardProps } 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();
+}
+
+const HIGHLIGHT_BORDERS: Record<string, string> = {
+  pinned: "var(--warning)",
+  answer: "var(--success)",
+};
+
+export function PostCard({
+  author,
+  content,
+  createdAt,
+  updatedAt,
+  actions,
+  highlight = "none",
+  indentLevel = 0,
+  className,
+  style,
+}: PostCardProps) {
+  const borderColor = HIGHLIGHT_BORDERS[highlight];
+
+  return (
+    <div
+      className={cn("rounded-md border border-border p-3", className)}
+      style={{
+        marginLeft: indentLevel ? `calc(${indentLevel} * 1rem)` : undefined,
+        ...(borderColor && {
+          borderLeftWidth: "3px",
+          borderLeftColor: borderColor,
+        }),
+        ...style,
+      }}
+    >
+      <div className="flex gap-2">
+        <UserAvatar
+          displayName={author.displayName}
+          avatarUrl={author.avatarUrl}
+          role={author.role as "student" | "instructor" | "ta" | "admin" | undefined}
+          size="medium"
+        />
+        <div className="flex-1 min-w-0">
+          <div className="flex items-center gap-1.5 flex-wrap text-sm">
+            <span className="font-semibold">{author.displayName}</span>
+            {author.role && author.role !== "student" && (
+              <span className="rounded-full bg-primary/10 px-1.5 py-0.5 text-xs font-medium text-primary capitalize">
+                {author.role}
+              </span>
+            )}
+            <span className="text-xs text-muted-foreground">
+              {formatTimestamp(createdAt)}
+            </span>
+            {updatedAt && (
+              <span className="text-xs text-muted-foreground italic">
+                (edited)
+              </span>
+            )}
+            {highlight === "pinned" && <Pin size={14} />}
+          </div>
+          <p className="mt-1 text-sm whitespace-pre-wrap">
+            {content}
+          </p>
+          {actions && (
+            <>
+              <Separator className="my-2" />
+              <div className="flex items-center gap-1">
+                {actions}
+              </div>
+            </>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/social/types.ts

@@ -0,0 +1,57 @@
+import type { ReactNode } from "react";
+
+/**
+ * UserAvatar renders a user avatar image with an initials fallback
+ * and an optional role badge.
+ *
+ * @example
+ * <UserAvatar displayName="Jane Smith" role="instructor" />
+ */
+export interface UserAvatarProps {
+  /** User's display name (used for initials fallback) */
+  displayName: string;
+  /** URL of the avatar image */
+  avatarUrl?: string;
+  /** User role — shown as a tooltip or small badge */
+  role?: "student" | "instructor" | "ta" | "admin";
+  /** Whether to show the role badge */
+  showRoleBadge?: boolean;
+  /** Avatar size */
+  size?: "small" | "medium" | "large";
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+/**
+ * PostCard renders a single discussion post or announcement with author info,
+ * timestamp, content body, and optional action buttons.
+ *
+ * @example
+ * <PostCard
+ *   author={{ displayName: "Jane Smith", role: "instructor" }}
+ *   content="Welcome to the course!"
+ *   createdAt="2025-01-15T10:30:00Z"
+ * />
+ */
+export interface PostCardProps {
+  /** Post author information */
+  author: { displayName: string; avatarUrl?: string; role?: string };
+  /** Post body content */
+  content: string;
+  /** Creation timestamp as ISO string */
+  createdAt: string;
+  /** Last update timestamp */
+  updatedAt?: string;
+  /** Action buttons rendered in the card footer */
+  actions?: ReactNode;
+  /** Highlight variant for special posts */
+  highlight?: "pinned" | "answer" | "none";
+  /** Indentation level for nested replies */
+  indentLevel?: number;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}

package/src/social/user-avatar.tsx

@@ -0,0 +1,76 @@
+import { useState } from "react";
+import type { UserAvatarProps } from "./types";
+import { cn } from "../lib/utils";
+
+const SIZES = { small: 28, medium: 36, large: 48 };
+
+const ROLE_LABELS: Record<string, string> = {
+  student: "Student",
+  instructor: "Instructor",
+  ta: "Teaching Assistant",
+  admin: "Admin",
+};
+
+const ROLE_COLORS: Record<string, string> = {
+  instructor: "var(--primary)",
+  ta: "var(--purple)",
+  admin: "var(--destructive)",
+  student: "var(--muted-foreground)",
+};
+
+function getInitials(name: string): string {
+  return name
+    .split(" ")
+    .filter(Boolean)
+    .map((w) => w[0])
+    .slice(0, 2)
+    .join("")
+    .toUpperCase();
+}
+
+export function UserAvatar({
+  displayName,
+  avatarUrl,
+  role,
+  showRoleBadge = false,
+  size = "medium",
+  className,
+  style,
+}: UserAvatarProps) {
+  const px = SIZES[size];
+  const fontSize = px * 0.4;
+  const [imgError, setImgError] = useState(false);
+
+  const showBadge = showRoleBadge && role && role !== "student";
+  const title = showBadge ? ROLE_LABELS[role] ?? role : undefined;
+
+  return (
+    <div
+      className={cn("relative inline-flex", className)}
+      style={style}
+      title={title}
+    >
+      <div
+        className="flex items-center justify-center rounded-full bg-muted text-muted-foreground overflow-hidden"
+        style={{ width: `${px}px`, height: `${px}px`, fontSize: `${fontSize}px` }}
+      >
+        {avatarUrl && !imgError ? (
+          <img
+            className="size-full object-cover"
+            src={avatarUrl}
+            alt={displayName}
+            onError={() => setImgError(true)}
+          />
+        ) : (
+          <span>{getInitials(displayName)}</span>
+        )}
+      </div>
+      {showBadge && (
+        <span
+          className="absolute -bottom-0.5 -right-0.5 size-2.5 rounded-full border-2 border-background"
+          style={{ background: ROLE_COLORS[role] ?? "var(--muted-foreground)" }}
+        />
+      )}
+    </div>
+  );
+}