@hydralms/components 0.1.0 → 0.1.2

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

package/src/flashcards/flashcard.tsx

@@ -0,0 +1,108 @@
+import { useState } from "react";
+import { RotateCcw } from "lucide-react";
+import type { FlashcardProps } from "./types";
+import { cn } from "../lib/utils";
+
+const COLOR_MAP: Record<string, { bg: string; border: string; accent: string }> = {
+  color1: { bg: "bg-blue-50 dark:bg-blue-950/40", border: "border-blue-200 dark:border-blue-800", accent: "bg-blue-200 dark:bg-blue-800" },
+  color2: { bg: "bg-violet-50 dark:bg-violet-950/40", border: "border-violet-200 dark:border-violet-800", accent: "bg-violet-200 dark:bg-violet-800" },
+  color3: { bg: "bg-emerald-50 dark:bg-emerald-950/40", border: "border-emerald-200 dark:border-emerald-800", accent: "bg-emerald-200 dark:bg-emerald-800" },
+  color4: { bg: "bg-amber-50 dark:bg-amber-950/40", border: "border-amber-200 dark:border-amber-800", accent: "bg-amber-200 dark:bg-amber-800" },
+  color5: { bg: "bg-rose-50 dark:bg-rose-950/40", border: "border-rose-200 dark:border-rose-800", accent: "bg-rose-200 dark:bg-rose-800" },
+  color6: { bg: "bg-green-50 dark:bg-green-950/40", border: "border-green-200 dark:border-green-800", accent: "bg-green-200 dark:bg-green-800" },
+};
+
+const SIZE_MAP: Record<string, { width: number; height: number; fontSize: string }> = {
+  small: { width: 280, height: 180, fontSize: "0.875rem" },
+  medium: { width: 400, height: 260, fontSize: "1rem" },
+  large: { width: 520, height: 340, fontSize: "1.125rem" },
+};
+
+export const Flashcard = ({
+  card,
+  isFlipped: controlledFlipped,
+  onFlip,
+  readOnly = false,
+  size = "medium",
+}: FlashcardProps) => {
+  const [internalFlipped, setInternalFlipped] = useState(false);
+
+  const isControlled = controlledFlipped !== undefined;
+  const isFlipped = isControlled ? controlledFlipped : internalFlipped;
+
+  const handleClick = () => {
+    if (readOnly) return;
+    if (isControlled) {
+      onFlip?.();
+    } else {
+      setInternalFlipped((prev) => !prev);
+      onFlip?.();
+    }
+  };
+
+  const { width, height, fontSize } = SIZE_MAP[size];
+  const colors = COLOR_MAP[card.color] || COLOR_MAP.color1;
+
+  return (
+    <div
+      className="perspective-[1000px]"
+      style={{ width: `${width}px`, height: `${height}px` }}
+    >
+      <div
+        className={cn(
+          "relative size-full transition-transform duration-500 transform-3d",
+          isFlipped && "transform-[rotateY(180deg)]",
+        )}
+      >
+        {/* Front */}
+        <div
+          className={cn(
+            "absolute inset-0 flex flex-col rounded-lg border backface-hidden",
+            colors.bg,
+            colors.border,
+            !readOnly && "cursor-pointer",
+          )}
+          onClick={handleClick}
+        >
+          <div className="flex flex-1 items-center justify-center p-5 overflow-auto">
+            <div
+              className="text-center"
+              style={{ fontSize }}
+              dangerouslySetInnerHTML={{ __html: card.front }}
+            />
+          </div>
+          {!readOnly && (
+            <div className="flex items-center justify-center gap-1 pb-3 text-muted-foreground">
+              <RotateCcw size={12} />
+              <span className="text-xs">Tap to flip</span>
+            </div>
+          )}
+        </div>
+
+        {/* Back */}
+        <div
+          className={cn(
+            "absolute inset-0 flex flex-col rounded-lg border border-border bg-background backface-hidden transform-[rotateY(180deg)]",
+            !readOnly && "cursor-pointer",
+          )}
+          onClick={handleClick}
+        >
+          <div className={cn("h-1.5 rounded-t-lg", colors.accent)} />
+          <div className="flex flex-1 items-start justify-center p-5 overflow-auto">
+            <div
+              className="text-left w-full flashcard-back-content"
+              style={{ fontSize }}
+              dangerouslySetInnerHTML={{ __html: card.back }}
+            />
+          </div>
+          {!readOnly && (
+            <div className="flex items-center justify-center gap-1 pb-3 text-muted-foreground">
+              <RotateCcw size={12} />
+              <span className="text-xs">Tap to flip back</span>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};

package/src/flashcards/index.ts

@@ -0,0 +1,3 @@
+export { Flashcard } from "./flashcard";
+export { FlashcardDeck } from "./flashcard-deck";
+export type { FlashcardData, FlashcardProps, FlashcardDeckProps } from "./types";

package/src/flashcards/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Flashcard component with 3D flip animation. Supports controlled and uncontrolled flip state.
+ *
+ * @example
+ * <Flashcard
+ *   card={{ uid: "1", front: "What is React?", back: "A JavaScript library for building UIs", color: "color1" }}
+ *   size="medium"
+ * />
+ */
+export interface FlashcardProps {
+  /** The flashcard data to display */
+  card: FlashcardData;
+  /** Controlled flip state — if provided, flip state is managed externally */
+  isFlipped?: boolean;
+  /** Called when the card is flipped */
+  onFlip?: () => void;
+  /** When true, disables the flip interaction */
+  readOnly?: boolean;
+  /** Card size variant */
+  size?: "small" | "medium" | "large";
+}
+
+/**
+ * FlashcardDeck component for navigating through a collection of flashcards.
+ *
+ * @example
+ * <FlashcardDeck
+ *   cards={cards}
+ *   deckName="React Fundamentals"
+ *   showProgress
+ *   onComplete={() => alert('Deck complete!')}
+ * />
+ */
+export interface FlashcardDeckProps {
+  /** Array of flashcard data to display */
+  cards: FlashcardData[];
+  /** Title shown above the deck */
+  deckName?: string;
+  /** Description shown below the deck name */
+  deckDescription?: string;
+  /** Controlled current card index */
+  currentIndex?: number;
+  /** Called when the user navigates to a different card */
+  onNavigate?: (index: number) => void;
+  /** Called when the user finishes the last card */
+  onComplete?: () => void;
+  /** When true, disables card flipping */
+  readOnly?: boolean;
+  /** Whether to show the progress bar and counter */
+  showProgress?: boolean;
+  /** Whether to shuffle the cards randomly */
+  shuffled?: boolean;
+}
+
+export interface FlashcardData {
+  uid: string;
+  front: string;
+  back: string;
+  color: string;
+}