@hydralms/components 0.1.0 → 0.1.2

package/src/sections/AssignmentSubmission/types.ts

@@ -0,0 +1,60 @@
+import type { ReactNode } from "react";
+
+/**
+ * AssignmentSubmission section — an assignment detail and submission view.
+ *
+ * Displays assignment instructions, due date, and submission status.
+ * Supports file upload, text, and URL submission types with draft saving
+ * and grade/feedback display.
+ *
+ * @example
+ * <AssignmentSubmission
+ *   title="Week 3 Essay"
+ *   instructions={<p>Write a 500-word essay on React.</p>}
+ *   dueDate="2025-03-15T23:59:00Z"
+ *   status="not_started"
+ *   submissionTypes={["text", "file"]}
+ *   onSubmit={(data) => submitAssignment(data)}
+ * />
+ */
+export interface AssignmentSubmissionProps {
+  /** Assignment title */
+  title: string;
+  /** Assignment instructions (rich content) */
+  instructions: ReactNode;
+  /** Due date as ISO string */
+  dueDate?: string;
+  /** Maximum score points */
+  maxScore?: number;
+  /** Current submission status */
+  status: "not_started" | "draft" | "submitted" | "late" | "graded" | "resubmit";
+  /** Allowed submission types */
+  submissionTypes: ("text" | "file" | "url")[];
+  /** Existing submission data for editing/viewing */
+  existingSubmission?: SubmissionData;
+  /** File upload constraints */
+  fileConstraints?: { maxFiles?: number; maxSizeMB?: number; acceptedTypes?: string };
+  /** Called on final submission */
+  onSubmit: (submission: SubmissionData) => void;
+  /** Called on draft save */
+  onSaveDraft?: (submission: SubmissionData) => void;
+  /** Grade data when already graded */
+  grade?: { score: number; feedback?: ReactNode };
+  /** Whether the submit action is in flight */
+  isSubmitting?: boolean;
+  /** When true, disables all interactions */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+export interface SubmissionData {
+  /** Text content */
+  textContent?: string;
+  /** Uploaded files */
+  files?: File[];
+  /** URL submission */
+  url?: string;
+}

package/src/sections/CertificateViewer/CertificateViewer.tsx

@@ -0,0 +1,117 @@
+import { Award, Download, Printer } from "lucide-react";
+import { Button } from "../../ui/button";
+import { Separator } from "../../ui/separator";
+import type { CertificateViewerProps } from "./types";
+import { cn } from "../../lib/utils";
+
+const VARIANT_CLASSES: Record<string, string> = {
+  classic: "border-[3px] border-double border-warning bg-linear-to-br from-[#fffbe6] to-[#fff8e1]",
+  modern: "border border-primary bg-linear-to-br from-[#fff5f5] to-[#fee2e2]",
+  minimal: "border border-border",
+};
+
+export function CertificateViewer({
+  recipientName,
+  courseTitle,
+  completionDate,
+  organizationName,
+  organizationLogo,
+  signatory,
+  certificateId,
+  variant = "classic",
+  showActions = true,
+  onPrint,
+  onDownload,
+  className,
+  style,
+}: CertificateViewerProps) {
+  const formattedDate = (() => {
+    try {
+      return new Date(completionDate).toLocaleDateString("en-US", {
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+      });
+    } catch {
+      return completionDate;
+    }
+  })();
+
+  function handlePrint() {
+    if (onPrint) {
+      onPrint();
+    } else {
+      window.print();
+    }
+  }
+
+  return (
+    <div className={className} style={style}>
+      <div
+        className={cn(
+          "p-3 sm:p-5 md:p-6 text-center max-w-200 mx-auto rounded-md",
+          VARIANT_CLASSES[variant],
+        )}
+      >
+        {/* Logo or icon */}
+        {organizationLogo ? (
+          <img
+            src={organizationLogo}
+            alt={organizationName}
+            className="h-15 mb-2 mx-auto block"
+          />
+        ) : (
+          <Award
+            size={48}
+            className={cn("mx-auto mb-4", variant === "classic" && "text-warning")}
+          />
+        )}
+
+        <p className="uppercase tracking-[3px] text-sm text-foreground/70">
+          Certificate of Completion
+        </p>
+
+        <Separator className="my-2 mx-auto max-w-50" />
+
+        <p className="text-sm text-foreground mb-1">This is to certify that</p>
+        <p className={cn("text-2xl font-bold mb-2 text-foreground", variant === "classic" && "font-serif")}>
+          {recipientName}
+        </p>
+        <p className="text-sm text-foreground mb-1">has successfully completed</p>
+        <p className="text-xl font-bold mb-2 text-primary">{courseTitle}</p>
+
+        <p className="text-sm text-foreground mb-3">
+          Issued by {organizationName} on {formattedDate}
+        </p>
+
+        {signatory && (
+          <div className="mt-4 mb-2">
+            <Separator className="my-2 mx-auto max-w-50" />
+            <p className="font-semibold text-sm text-foreground">{signatory.name}</p>
+            <p className="text-xs text-muted-foreground">{signatory.title}</p>
+          </div>
+        )}
+
+        {certificateId && (
+          <span className="block text-xs text-muted-foreground mt-2">
+            Certificate ID: {certificateId}
+          </span>
+        )}
+      </div>
+
+      {/* Actions */}
+      {showActions && (
+        <div className="flex justify-center gap-2 mt-3">
+          <Button variant="outline" onClick={handlePrint}>
+            <Printer size={16} /> Print
+          </Button>
+          {onDownload && (
+            <Button variant="outline" onClick={onDownload}>
+              <Download size={16} /> Download
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/sections/CertificateViewer/types.ts

@@ -0,0 +1,45 @@
+
+/**
+ * CertificateViewer section — a printable completion certificate.
+ *
+ * Displays a certificate with recipient details, course information,
+ * signatory, and verification ID. Supports three visual variants:
+ * classic, modern, and minimal.
+ *
+ * @example
+ * <CertificateViewer
+ *   recipientName="Jane Smith"
+ *   courseTitle="Advanced React"
+ *   completionDate="2025-03-01"
+ *   organizationName="HydraLMS Academy"
+ *   variant="modern"
+ * />
+ */
+export interface CertificateViewerProps {
+  /** Recipient's full name */
+  recipientName: string;
+  /** Course or program title */
+  courseTitle: string;
+  /** Completion date as ISO string or human-readable string */
+  completionDate: string;
+  /** Issuing organization name */
+  organizationName: string;
+  /** Organization logo URL */
+  organizationLogo?: string;
+  /** Signatory information */
+  signatory?: { name: string; title: string };
+  /** Unique certificate ID */
+  certificateId?: string;
+  /** Certificate template variant */
+  variant?: "classic" | "modern" | "minimal";
+  /** Whether to show print/download actions */
+  showActions?: boolean;
+  /** Called when print is triggered */
+  onPrint?: () => void;
+  /** Called when download is triggered */
+  onDownload?: () => void;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}

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