@hydralms/components 0.1.1 → 0.1.3

package/src/curriculum/curriculum-item.tsx

@@ -0,0 +1,81 @@
+import { ChevronRight, ChevronDown, CheckCircle2, Circle } from "lucide-react";
+import { LearningObjectIcon } from "./learning-object-icon";
+import { formatDuration } from "../utils/format-duration";
+import type { CurriculumItemRowProps } from "./types";
+import { cn } from "../lib/utils";
+
+export const CurriculumItemRow = ({
+  item,
+  level,
+  isActive = false,
+  isCompleted = false,
+  isExpanded = false,
+  hasChildren,
+  onToggleExpand,
+  onClick,
+  showDuration = true,
+  showIcon = true,
+  showProgress = true,
+}: CurriculumItemRowProps) => {
+  const isModule = hasChildren;
+
+  const fontWeightClass = isModule ? "font-semibold" : isActive ? "font-medium" : "font-normal";
+
+  return (
+    <div
+      className={cn(
+        "flex items-center gap-2 py-2 pr-3 transition-colors",
+        onClick && "cursor-pointer hover:bg-muted",
+        isActive && "bg-secondary",
+      )}
+      style={{ paddingLeft: `${(level * 20) + 8}px` }}
+      onClick={onClick}
+    >
+      <div className="shrink-0 flex items-center justify-center size-5">
+        {showProgress && isCompleted ? (
+          <span className="text-success">
+            <CheckCircle2 size={18} />
+          </span>
+        ) : showIcon ? (
+          <span className={isActive ? "text-primary" : "text-muted-foreground"}>
+            <LearningObjectIcon type={item.type} size={16} />
+          </span>
+        ) : (
+          <span className="text-muted-foreground">
+            <Circle size={16} />
+          </span>
+        )}
+      </div>
+
+      <div className="flex-1 min-w-0">
+        <div
+          className={cn("text-sm truncate", isActive ? "text-primary" : "text-foreground", fontWeightClass)}
+        >
+          {item.name}
+        </div>
+        {showDuration && item.duration > 0 && !isModule && (
+          <div className="text-xs text-muted-foreground mt-0.5">
+            {formatDuration(item.duration)}
+          </div>
+        )}
+      </div>
+
+      {hasChildren && (
+        <button
+          className="inline-flex items-center justify-center rounded-md p-1 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground"
+          aria-label={isExpanded ? "Collapse" : "Expand"}
+          onClick={(e) => {
+            e.stopPropagation();
+            onToggleExpand?.();
+          }}
+        >
+          {isExpanded ? (
+            <ChevronDown size={16} />
+          ) : (
+            <ChevronRight size={16} />
+          )}
+        </button>
+      )}
+    </div>
+  );
+};

package/src/curriculum/curriculum-tree.tsx

@@ -0,0 +1,69 @@
+import { useState } from "react";
+import { CurriculumItemRow } from "./curriculum-item";
+import type { CurriculumTreeProps, CurriculumItem } from "./types";
+
+export const CurriculumTree = ({
+  items,
+  progress,
+  activeItemUid,
+  onItemClick,
+  readOnly = false,
+  showDuration = true,
+  showIcons = true,
+  showProgress = true,
+}: CurriculumTreeProps) => {
+  const [expanded, setExpanded] = useState<Record<string, boolean>>({});
+
+  if (!items || items.length === 0) {
+    return null;
+  }
+
+  const handleToggleExpand = (uid: string) => {
+    setExpanded((prev) => ({ ...prev, [uid]: !prev[uid] }));
+  };
+
+  const isItemCompleted = (uid: string): boolean => {
+    if (!progress || !showProgress) return false;
+    return progress.some((p) => p.resourceUid === uid && p.isCompleted);
+  };
+
+  const renderItems = (
+    nodeItems: CurriculumItem[],
+    level: number,
+  ) => {
+    return (
+      <div className="flex flex-col">
+        {nodeItems.map((item) => {
+          const hasChildren = !!item.children?.length;
+          const isExpanded = expanded[item.uid] || false;
+
+          return (
+            <div key={item.uid}>
+              <CurriculumItemRow
+                item={item}
+                level={level}
+                isActive={activeItemUid === item.uid}
+                isCompleted={isItemCompleted(item.uid)}
+                isExpanded={isExpanded}
+                hasChildren={hasChildren}
+                onToggleExpand={() => handleToggleExpand(item.uid)}
+                onClick={readOnly ? undefined : () => onItemClick?.(item)}
+                showDuration={showDuration}
+                showIcon={showIcons}
+                showProgress={showProgress}
+              />
+
+              {hasChildren && isExpanded && renderItems(item.children!, level + 1)}
+            </div>
+          );
+        })}
+      </div>
+    );
+  };
+
+  return (
+    <nav className="rounded-lg border border-border overflow-hidden">
+      {renderItems(items, 0)}
+    </nav>
+  );
+};

package/src/curriculum/index.ts

@@ -0,0 +1,11 @@
+export { CurriculumTree } from "./curriculum-tree";
+export { CurriculumItemRow } from "./curriculum-item";
+export { LearningObjectIcon } from "./learning-object-icon";
+
+export type {
+  CurriculumItem,
+  CurriculumItemProgress,
+  CurriculumTreeProps,
+  CurriculumItemRowProps,
+  LearningObjectIconProps,
+} from "./types";

package/src/curriculum/learning-object-icon.tsx

@@ -0,0 +1,44 @@
+import {
+  Video,
+  FileText,
+  HelpCircle,
+  ClipboardList,
+  MessageSquare,
+  ExternalLink,
+  Music,
+  Image,
+  Code,
+  BookOpen,
+  PlayCircle,
+  type LucideIcon,
+} from "lucide-react";
+import type { LearningObjectIconProps } from "./types";
+
+const ICON_MAP: Record<string, LucideIcon> = {
+  video: Video,
+  video_lesson: Video,
+  stream: PlayCircle,
+  document: FileText,
+  pdf: FileText,
+  page: FileText,
+  quiz: HelpCircle,
+  assessment: HelpCircle,
+  assignment: ClipboardList,
+  discussion: MessageSquare,
+  link: ExternalLink,
+  url: ExternalLink,
+  audio: Music,
+  image: Image,
+  scorm: Code,
+  iframe: Code,
+  lesson: BookOpen,
+  module: BookOpen,
+};
+
+export const LearningObjectIcon = ({
+  type,
+  size = 18,
+}: LearningObjectIconProps) => {
+  const IconComponent = ICON_MAP[type] ?? FileText;
+  return <IconComponent size={size} />;
+};

package/src/curriculum/types.ts

@@ -0,0 +1,83 @@
+/**
+ * CurriculumTree component for rendering a hierarchical course curriculum with expand/collapse support.
+ *
+ * @example
+ * <CurriculumTree
+ *   items={curriculum}
+ *   progress={userProgress}
+ *   activeItemUid={currentLessonUid}
+ *   onItemClick={(item) => navigate(item.uid)}
+ *   showProgress
+ * />
+ */
+export interface CurriculumTreeProps {
+  /** Hierarchical curriculum items to display */
+  items: CurriculumItem[];
+  /** User progress data for completion indicators */
+  progress?: CurriculumItemProgress[];
+  /** UID of the currently active item */
+  activeItemUid?: string;
+  /** Called when the user clicks a curriculum item */
+  onItemClick?: (item: CurriculumItem) => void;
+  /** When true, disables item click interactions */
+  readOnly?: boolean;
+  /** Whether to show estimated duration for each item */
+  showDuration?: boolean;
+  /** Whether to show learning object type icons */
+  showIcons?: boolean;
+  /** Whether to show completion progress indicators */
+  showProgress?: boolean;
+}
+
+/**
+ * CurriculumItemRow renders a single row in the curriculum tree.
+ *
+ * @example
+ * <CurriculumItemRow
+ *   item={item}
+ *   level={0}
+ *   isActive
+ *   hasChildren={false}
+ * />
+ */
+export interface CurriculumItemRowProps {
+  item: CurriculumItem;
+  level: number;
+  isActive?: boolean;
+  isCompleted?: boolean;
+  isExpanded?: boolean;
+  hasChildren: boolean;
+  onToggleExpand?: () => void;
+  onClick?: () => void;
+  showDuration?: boolean;
+  showIcon?: boolean;
+  showProgress?: boolean;
+}
+
+/**
+ * LearningObjectIcon renders the appropriate icon for a given learning object type.
+ *
+ * @example
+ * <LearningObjectIcon type="video" size={18} />
+ */
+export interface LearningObjectIconProps {
+  /** Learning object type string (e.g. "video", "quiz", "document") */
+  type: string;
+  /** Icon size in pixels */
+  size?: number;
+}
+
+export interface CurriculumItem {
+  uid: string;
+  name: string;
+  type: string;
+  duration: number;
+  sequence: number;
+  children?: CurriculumItem[];
+}
+
+export interface CurriculumItemProgress {
+  resourceUid: string;
+  isCompleted: boolean;
+  timeSpent?: number;
+}

package/src/feedback/feedback-banner.tsx

@@ -0,0 +1,46 @@
+import { CheckCircle, XCircle } from "lucide-react";
+import type { FeedbackBannerProps } from "./types";
+import { cn } from "../lib/utils";
+
+export function FeedbackBanner({
+  isCorrect,
+  explanation,
+  onRetry,
+  retryLabel = "Try Again",
+  className,
+  style,
+}: FeedbackBannerProps) {
+  return (
+    <div
+      role="alert"
+      className={cn(
+        "flex items-start gap-2 rounded-md border p-3 text-sm",
+        isCorrect
+          ? "border-success/50 bg-success/5"
+          : "border-destructive/50 bg-destructive/5",
+        className,
+      )}
+      style={style}
+    >
+      <span className={cn("shrink-0", isCorrect ? "text-success" : "text-destructive")}>
+        {isCorrect ? <CheckCircle size={20} /> : <XCircle size={20} />}
+      </span>
+      <div className="flex-1">
+        <div className="flex items-start justify-between gap-2">
+          <div>
+            <span className="font-semibold">{isCorrect ? "Correct!" : "Incorrect"}</span>
+            {explanation && <p className="mt-1 text-foreground">{explanation}</p>}
+          </div>
+          {!isCorrect && onRetry && (
+            <button
+              className="shrink-0 rounded-md border border-border bg-background px-3 py-1 text-sm font-medium transition-colors hover:bg-muted"
+              onClick={onRetry}
+            >
+              {retryLabel}
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/feedback/index.ts

@@ -0,0 +1,8 @@
+export { FeedbackBanner } from "./feedback-banner";
+export { LikertScale } from "./likert-scale";
+export { StarRating } from "./star-rating";
+export type {
+  FeedbackBannerProps,
+  LikertScaleProps,
+  StarRatingProps,
+} from "./types";

package/src/feedback/likert-scale.tsx

@@ -0,0 +1,58 @@
+import type { LikertScaleProps } from "./types";
+import { cn } from "../lib/utils";
+
+export function LikertScale({
+  value,
+  onChange,
+  points = 5,
+  lowLabel = "Strongly Disagree",
+  highLabel = "Strongly Agree",
+  disabled = false,
+  readOnly = false,
+  className,
+  style,
+}: LikertScaleProps) {
+  const options = Array.from({ length: points }, (_, i) => i + 1);
+  const isInteractive = !disabled && !readOnly;
+
+  return (
+    <div className={cn("flex flex-col gap-1", className)} style={style}>
+      <div className="flex flex-row" role="radiogroup">
+        {options.map((n) => {
+          const isSelected = value === n;
+
+          return (
+            <label
+              key={n}
+              className={cn(
+                "flex items-center justify-center border border-border px-1.5 py-2 text-sm transition-colors first:rounded-l-md last:rounded-r-md -ml-px first:ml-0",
+                isSelected
+                  ? "bg-primary text-primary-foreground border-primary z-10"
+                  : "bg-background text-foreground",
+                !isInteractive && "opacity-60 cursor-not-allowed",
+                isInteractive && !isSelected && "cursor-pointer hover:bg-muted",
+              )}
+            >
+              <input
+                type="radio"
+                name="likert-scale"
+                className="sr-only"
+                value={n}
+                checked={isSelected}
+                disabled={disabled}
+                onChange={() => {
+                  if (isInteractive) onChange(n);
+                }}
+              />
+              <span className="text-sm font-medium">{n}</span>
+            </label>
+          );
+        })}
+      </div>
+      <div className="flex justify-between">
+        <span className="text-xs text-muted-foreground">{lowLabel}</span>
+        <span className="text-xs text-muted-foreground">{highLabel}</span>
+      </div>
+    </div>
+  );
+}

package/src/feedback/star-rating.tsx

@@ -0,0 +1,65 @@
+import { useState } from "react";
+import { Star } from "lucide-react";
+import type { StarRatingProps } from "./types";
+import { cn } from "../lib/utils";
+
+const SIZES = { small: 18, medium: 24, large: 32 };
+
+export function StarRating({
+  value,
+  onChange,
+  maxStars = 5,
+  allowHalf = false,
+  size = "medium",
+  disabled = false,
+  readOnly = false,
+  className,
+  style,
+}: StarRatingProps) {
+  const [hoverValue, setHoverValue] = useState<number | null>(null);
+  const iconSize = SIZES[size];
+  const displayValue = hoverValue ?? value;
+  const isInteractive = !disabled && !readOnly;
+
+  function handleClick(starIndex: number) {
+    if (!isInteractive) return;
+    onChange(starIndex);
+  }
+
+  return (
+    <div
+      className={cn("inline-flex gap-0.5", className)}
+      style={style}
+      onMouseLeave={() => isInteractive && setHoverValue(null)}
+    >
+      {Array.from({ length: maxStars }, (_, i) => {
+        const starValue = i + 1;
+        const isFilled = displayValue >= starValue;
+        const isHalf = allowHalf && !isFilled && displayValue >= starValue - 0.5;
+
+        return (
+          <button
+            key={i}
+            type="button"
+            className={cn(
+              "inline-flex items-center justify-center rounded-md border-none bg-transparent p-0",
+              isInteractive ? "cursor-pointer" : "cursor-default",
+              isFilled || isHalf ? "text-warning" : "text-muted-foreground",
+            )}
+            disabled={disabled}
+            onClick={() => handleClick(starValue)}
+            onMouseEnter={() => isInteractive && setHoverValue(starValue)}
+            aria-label={`Rate ${starValue} star${starValue !== 1 ? "s" : ""}`}
+          >
+            <Star
+              size={iconSize}
+              fill={isFilled ? "currentColor" : isHalf ? "currentColor" : "none"}
+              strokeWidth={1.5}
+              style={isHalf ? { clipPath: "inset(0 50% 0 0)" } : undefined}
+            />
+          </button>
+        );
+      })}
+    </div>
+  );
+}

package/src/feedback/types.ts

@@ -0,0 +1,86 @@
+
+/**
+ * FeedbackBanner shows a correct/incorrect status banner with an optional
+ * explanation and retry button after answering a question.
+ *
+ * @example
+ * <FeedbackBanner
+ *   isCorrect={false}
+ *   explanation="The correct answer is React because it uses a virtual DOM."
+ *   onRetry={() => resetAnswer()}
+ * />
+ */
+export interface FeedbackBannerProps {
+  /** Whether the answer was correct */
+  isCorrect: boolean;
+  /** Explanation text shown below the status */
+  explanation?: string;
+  /** Called when the user clicks the retry button */
+  onRetry?: () => void;
+  /** Label for the retry button */
+  retryLabel?: string;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+/**
+ * LikertScale renders a horizontal 5 or 7 point agreement scale
+ * commonly used in surveys and feedback forms.
+ *
+ * @example
+ * <LikertScale
+ *   value={3}
+ *   onChange={(v) => setRating(v)}
+ *   lowLabel="Strongly Disagree"
+ *   highLabel="Strongly Agree"
+ * />
+ */
+export interface LikertScaleProps {
+  /** Currently selected value (1-based), or null if none selected */
+  value: number | null;
+  /** Called when the user selects a point */
+  onChange: (value: number) => void;
+  /** Number of scale points */
+  points?: 5 | 7;
+  /** Label for the low end of the scale */
+  lowLabel?: string;
+  /** Label for the high end of the scale */
+  highLabel?: string;
+  /** Whether the input is disabled */
+  disabled?: boolean;
+  /** When true, disables interaction */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+/**
+ * StarRating renders a 1–5 star rating input with hover preview.
+ *
+ * @example
+ * <StarRating value={4} onChange={(v) => setRating(v)} />
+ */
+export interface StarRatingProps {
+  /** Current rating value */
+  value: number;
+  /** Called when the user selects a rating */
+  onChange: (value: number) => void;
+  /** Maximum number of stars */
+  maxStars?: number;
+  /** Whether to allow half-star increments */
+  allowHalf?: boolean;
+  /** Star size */
+  size?: "small" | "medium" | "large";
+  /** Whether the input is disabled */
+  disabled?: boolean;
+  /** When true, disables interaction */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}

package/src/flashcards/flashcard-deck.tsx

@@ -0,0 +1,130 @@
+import { useState, useMemo } from "react";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { Flashcard } from "./flashcard";
+import { Button } from "../ui/button";
+import type { FlashcardDeckProps } from "./types";
+
+function shuffle<T>(array: T[]): T[] {
+  const shuffled = [...array];
+  for (let i = shuffled.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+  }
+  return shuffled;
+}
+
+export const FlashcardDeck = ({
+  cards,
+  deckName,
+  deckDescription,
+  currentIndex: controlledIndex,
+  onNavigate,
+  onComplete,
+  readOnly = false,
+  showProgress = true,
+  shuffled = false,
+}: FlashcardDeckProps) => {
+  const orderedCards = useMemo(
+    () => (shuffled ? shuffle(cards) : cards),
+    [cards, shuffled],
+  );
+
+  const [internalIndex, setInternalIndex] = useState(0);
+  const [isFlipped, setIsFlipped] = useState(false);
+
+  const isControlled = controlledIndex !== undefined;
+  const currentIndex = isControlled ? controlledIndex : internalIndex;
+  const currentCard = orderedCards[currentIndex];
+
+  const hasPrevious = currentIndex > 0;
+  const hasNext = currentIndex < orderedCards.length - 1;
+
+  const handleNavigate = (index: number) => {
+    setIsFlipped(false);
+    if (isControlled) {
+      onNavigate?.(index);
+    } else {
+      setInternalIndex(index);
+    }
+  };
+
+  const handlePrevious = () => {
+    if (hasPrevious) handleNavigate(currentIndex - 1);
+  };
+
+  const handleNext = () => {
+    if (hasNext) {
+      handleNavigate(currentIndex + 1);
+    } else {
+      onComplete?.();
+    }
+  };
+
+  if (!orderedCards.length) {
+    return (
+      <span className="text-sm text-muted-foreground">
+        No flashcards in this deck.
+      </span>
+    );
+  }
+
+  const progress = ((currentIndex + 1) / orderedCards.length) * 100;
+
+  return (
+    <div className="flex flex-col items-center gap-4">
+      {(deckName || deckDescription) && (
+        <div className="flex flex-col gap-0.5 text-center">
+          {deckName && (
+            <span className="text-lg font-semibold">{deckName}</span>
+          )}
+          {deckDescription && (
+            <span className="text-sm text-muted-foreground">{deckDescription}</span>
+          )}
+        </div>
+      )}
+
+      {currentCard && (
+        <Flashcard
+          card={currentCard}
+          isFlipped={isFlipped}
+          onFlip={() => setIsFlipped((prev) => !prev)}
+          readOnly={readOnly}
+        />
+      )}
+
+      {showProgress && (
+        <div className="flex w-full items-center gap-2">
+          <div className="flex-1 h-1.5 rounded-full bg-muted overflow-hidden">
+            <div
+              className="h-full rounded-full bg-primary transition-[width] duration-300"
+              style={{ width: `${progress}%` }}
+            />
+          </div>
+          <span className="text-xs text-muted-foreground whitespace-nowrap">
+            {currentIndex + 1} of {orderedCards.length}
+          </span>
+        </div>
+      )}
+
+      <div className="flex w-full items-center justify-between gap-3">
+        <Button
+          variant="outline"
+          size="sm"
+          className="rounded-lg"
+          disabled={!hasPrevious}
+          onClick={handlePrevious}
+        >
+          <ChevronLeft size={16} /> Previous
+        </Button>
+
+        <Button
+          size="sm"
+          className="rounded-lg"
+          onClick={handleNext}
+        >
+          {hasNext ? "Next" : "Finish"} <ChevronRight size={16} />
+        </Button>
+      </div>
+    </div>
+  );
+};