@hydralms/components 0.1.3 → 0.3.0

package/src/provider/HydraProvider.tsx

@@ -1,10 +1,15 @@
 import "../styles/globals.css";
 import type { ReactNode } from "react";
+import { HydraLicenseProvider } from "../license/HydraContext";
 
 export interface HydraProviderProps {
   children: ReactNode;
   /** Controls color mode. Defaults to `"dark"`. Set to `"light"` to use the light theme. */
   colorMode?: "light" | "dark";
+  /** HydraLMS Pro license key. Omit for free tier. */
+  licenseKey?: string;
+  /** Validation endpoint URL. When empty (default), all features are unlocked (dev mode). */
+  validateUrl?: string;
   className?: string;
   style?: React.CSSProperties;
 }
@@ -12,15 +17,19 @@ export interface HydraProviderProps {
 export function HydraProvider({
   children,
   colorMode = "dark",
+  licenseKey,
+  validateUrl,
   className,
   style,
 }: HydraProviderProps) {
   return (
-    <div
-      className={`hydra-root${colorMode === "dark" ? " dark" : ""}${className ? ` ${className}` : ""}`}
-      style={style}
-    >
-      {children}
-    </div>
+    <HydraLicenseProvider licenseKey={licenseKey} validateUrl={validateUrl}>
+      <div
+        className={`hydra-root${colorMode === "dark" ? " dark" : ""}${className ? ` ${className}` : ""}`}
+        style={style}
+      >
+        {children}
+      </div>
+    </HydraLicenseProvider>
   );
 }

package/src/questions/choice.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect } from "react";
+import { useState, useMemo, memo } from "react";
 import type { QuestionProps } from "./types";
 import { Alert, AlertDescription } from "../ui/alert";
 import { cn } from "../lib/utils";
@@ -12,18 +12,21 @@ import { cn } from "../lib/utils";
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const Choice = ({
+export const Choice = memo(function Choice({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
-  const [selectedAnswer, setSelectedAnswer] = useState<string>("");
+}: QuestionProps) {
+  const [selectedAnswer, setSelectedAnswer] = useState<string>(
+    () => sessionAnswers?.[0]?.answerUid || "",
+  );
 
-  const sortedAnswers = [...(question.answers || [])].sort(
-    (a, b) => a.sequence - b.sequence,
+  const sortedAnswers = useMemo(
+    () => [...(question.answers || [])].sort((a, b) => a.sequence - b.sequence),
+    [question.answers],
   );
 
   const handleChange = (uid: string) => {
@@ -33,11 +36,6 @@ export const Choice = ({
     onAnswer?.([{ uid }]);
   };
 
-  useEffect(() => {
-    const current = sessionAnswers?.[0]?.answerUid || "";
-    setSelectedAnswer(current);
-  }, [sessionAnswers]);
-
   const getAnswerClasses = (answerUid: string) => {
     if (!showCorrectAnswers) return "px-2";
 
@@ -55,7 +53,8 @@ export const Choice = ({
     <div className="flex flex-col gap-4">
       <div dangerouslySetInnerHTML={{ __html: question.content }} />
 
-      <div className="flex flex-col gap-2">
+      <fieldset className="flex flex-col gap-2 border-0 p-0 m-0">
+        <legend className="sr-only">Answer choices</legend>
         {sortedAnswers.map((answer) => (
           <div
             key={answer.uid}
@@ -72,10 +71,16 @@ export const Choice = ({
                 className="accent-primary m-0 shrink-0"
               />
               <span dangerouslySetInnerHTML={{ __html: answer.content }} />
+              {showCorrectAnswers && answer.isCorrect && (
+                <span className="sr-only">(Correct answer)</span>
+              )}
+              {showCorrectAnswers && selectedAnswer === answer.uid && !answer.isCorrect && (
+                <span className="sr-only">(Your answer — incorrect)</span>
+              )}
             </label>
           </div>
         ))}
-      </div>
+      </fieldset>
 
       {showCorrectAnswers && question.explanation && (
         <Alert className="mt-2">
@@ -87,4 +92,4 @@ export const Choice = ({
       )}
     </div>
   );
-};
+});

package/src/questions/confidence-indicator.tsx

@@ -0,0 +1,107 @@
+import { memo } from "react";
+import type { ReactNode } from "react";
+import { HelpCircle, Brain, Lightbulb } from "lucide-react";
+import { cn } from "../lib/utils";
+
+/** A single confidence level option. */
+export interface ConfidenceLevel {
+  /** Value stored in SessionAnswer.confidence */
+  value: string;
+  /** Display label */
+  label: string;
+  /** Optional icon */
+  icon?: ReactNode;
+}
+
+/**
+ * ConfidenceIndicator lets learners self-report their answer confidence,
+ * supporting metacognitive assessment strategies.
+ *
+ * @example
+ * <ConfidenceIndicator
+ *   value={answer.confidence}
+ *   onChange={(level) => updateConfidence(level)}
+ * />
+ */
+export interface ConfidenceIndicatorProps {
+  /** Currently selected confidence level value */
+  value: string | null;
+  /** Called when the user selects a confidence level */
+  onChange: (level: string) => void;
+  /** Custom confidence levels (defaults to 3 levels) */
+  levels?: ConfidenceLevel[];
+  /** When true, disables interaction */
+  disabled?: boolean;
+  /** When true, shows selected state but disables interaction */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}
+
+const DEFAULT_LEVELS: ConfidenceLevel[] = [
+  {
+    value: "low",
+    label: "Guessing",
+    icon: <HelpCircle className="size-3.5" />,
+  },
+  {
+    value: "medium",
+    label: "Somewhat sure",
+    icon: <Brain className="size-3.5" />,
+  },
+  {
+    value: "high",
+    label: "Confident",
+    icon: <Lightbulb className="size-3.5" />,
+  },
+];
+
+export const ConfidenceIndicator = memo(function ConfidenceIndicator({
+  value,
+  onChange,
+  levels = DEFAULT_LEVELS,
+  disabled = false,
+  readOnly = false,
+  className,
+  style,
+}: ConfidenceIndicatorProps) {
+  const isDisabled = disabled || readOnly;
+
+  return (
+    <div
+      data-slot="confidence-indicator"
+      className={cn("flex items-center gap-1", className)}
+      style={style}
+      role="radiogroup"
+      aria-label="Confidence level"
+    >
+      {levels.map((level) => {
+        const isSelected = value === level.value;
+        return (
+          <button
+            key={level.value}
+            type="button"
+            role="radio"
+            aria-checked={isSelected}
+            aria-label={level.label}
+            disabled={isDisabled}
+            onClick={() => onChange(level.value)}
+            className={cn(
+              "inline-flex items-center gap-1.5 rounded-full px-3 py-1 text-xs font-medium transition-all",
+              "border outline-none focus-visible:ring-2 focus-visible:ring-ring/50",
+              isSelected
+                ? "border-primary bg-primary/10 text-primary"
+                : "border-transparent bg-muted text-muted-foreground hover:bg-muted/80",
+              isDisabled && "opacity-50 pointer-events-none",
+            )}
+          >
+            {level.icon}
+            {level.label}
+          </button>
+        );
+      })}
+    </div>
+  );
+});

package/src/questions/essay.tsx

@@ -1,10 +1,10 @@
-import { useState, useEffect, useCallback } from "react";
+import { useState, useMemo, useRef, useEffect, memo } from "react";
 import { debounce } from "../utils/debounce";
-import { Textarea } from "../ui/textarea";
+import { RichTextEditor } from "../ui/rich-text-editor";
 import type { QuestionProps } from "./types";
 
 /**
- * Essay renders a long-form text input question with a multiline textarea.
+ * Essay renders a long-form rich text input question.
  *
  * @example
  * <Essay
@@ -12,48 +12,48 @@ import type { QuestionProps } from "./types";
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const Essay = ({
+export const Essay = memo(function Essay({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   disabled = false,
-}: QuestionProps) => {
-  const [value, setValue] = useState("");
+}: QuestionProps) {
+  const [value, setValue] = useState(() => sessionAnswers?.[0]?.content || "");
 
-  const debouncedAnswer = useCallback(
-    debounce((content: string) => {
-      onAnswer?.([
-        {
-          uid: question.answers?.[0]?.uid || question.uid,
-          content,
-        },
-      ]);
-    }, 500),
-    [onAnswer, question.answers, question.uid],
+  const onAnswerRef = useRef(onAnswer);
+  onAnswerRef.current = onAnswer;
+  const answerUidRef = useRef(question.answers?.[0]?.uid || question.uid);
+  answerUidRef.current = question.answers?.[0]?.uid || question.uid;
+
+  const debouncedAnswer = useMemo(
+    () =>
+      debounce((content: string) => {
+        onAnswerRef.current?.([{ uid: answerUidRef.current, content }]);
+      }, 500),
+    [],
   );
+  useEffect(() => () => debouncedAnswer.cancel(), [debouncedAnswer]);
 
-  const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
-    const newValue = e.target.value;
-    setValue(newValue);
-    debouncedAnswer(newValue);
+  const handleChange = (html: string) => {
+    setValue(html);
+    debouncedAnswer(html);
   };
 
-  useEffect(() => {
-    setValue(sessionAnswers?.[0]?.content || "");
-  }, [sessionAnswers]);
-
   return (
     <div className="flex flex-col gap-2">
       <div dangerouslySetInnerHTML={{ __html: question.content }} />
 
-      <Textarea
-        className="min-h-30 resize-y"
+      <RichTextEditor
+        className="min-h-30"
         value={value}
         onChange={handleChange}
         placeholder="Write your response here..."
-        disabled={readOnly || disabled}
+        readOnly={readOnly}
+        disabled={disabled}
+        variant="default"
+        ariaLabel="Essay response"
       />
     </div>
   );
-};
+});

package/src/questions/fill-in-the-blank.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, useCallback } from "react";
+import { useState, useMemo, useRef, useId, useEffect, memo } from "react";
 import { debounce } from "../utils/debounce";
 import { Input } from "../ui/input";
 import { Alert, AlertDescription } from "../ui/alert";
@@ -13,27 +13,30 @@ import type { QuestionProps } from "./types";
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const FillInTheBlank = ({
+export const FillInTheBlank = memo(function FillInTheBlank({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
-  const [value, setValue] = useState("");
+}: QuestionProps) {
+  const inputId = useId();
+  const [value, setValue] = useState(() => sessionAnswers?.[0]?.content || "");
 
-  const debouncedAnswer = useCallback(
-    debounce((content: string) => {
-      onAnswer?.([
-        {
-          uid: question.answers?.[0]?.uid || "",
-          content,
-        },
-      ]);
-    }, 300),
-    [onAnswer, question.answers],
+  const onAnswerRef = useRef(onAnswer);
+  onAnswerRef.current = onAnswer;
+  const answerUidRef = useRef(question.answers?.[0]?.uid || "");
+  answerUidRef.current = question.answers?.[0]?.uid || "";
+
+  const debouncedAnswer = useMemo(
+    () =>
+      debounce((content: string) => {
+        onAnswerRef.current?.([{ uid: answerUidRef.current, content }]);
+      }, 300),
+    [],
   );
+  useEffect(() => () => debouncedAnswer.cancel(), [debouncedAnswer]);
 
   const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     const newValue = e.target.value;
@@ -41,15 +44,13 @@ export const FillInTheBlank = ({
     debouncedAnswer(newValue);
   };
 
-  useEffect(() => {
-    setValue(sessionAnswers?.[0]?.content || "");
-  }, [sessionAnswers]);
-
   return (
     <div className="flex flex-col gap-2">
       <div dangerouslySetInnerHTML={{ __html: question.content }} />
 
+      <label htmlFor={inputId} className="sr-only">Your answer</label>
       <Input
+        id={inputId}
         value={value}
         onChange={handleChange}
         placeholder="Type your answer here..."
@@ -66,4 +67,4 @@ export const FillInTheBlank = ({
       )}
     </div>
   );
-};
+});

package/src/questions/hotspot.tsx

@@ -0,0 +1,154 @@
+import { useState, useMemo, memo } from "react";
+import { Alert, AlertDescription } from "../ui/alert";
+import { cn } from "../lib/utils";
+import type { QuestionProps, HotspotRegion } from "./types";
+
+function getRegionStyle(region: HotspotRegion): React.CSSProperties {
+  if (region.shape === "rect") {
+    const [x, y, w, h] = region.coords;
+    return {
+      left: `${x}%`,
+      top: `${y}%`,
+      width: `${w}%`,
+      height: `${h}%`,
+    };
+  }
+  // circle: [cx, cy, r]
+  const [cx, cy, r] = region.coords;
+  return {
+    left: `${cx - r}%`,
+    top: `${cy - r}%`,
+    width: `${r * 2}%`,
+    height: `${r * 2}%`,
+    borderRadius: "50%",
+  };
+}
+
+/**
+ * Hotspot renders an image with clickable regions for selection.
+ *
+ * Regions are positioned using percentage-based coordinates so they scale with the image.
+ *
+ * @example
+ * <Hotspot
+ *   question={{
+ *     uid: "q1",
+ *     type: "hotspot",
+ *     content: "Click on the heart.",
+ *     hotspotImageUrl: "/anatomy.png",
+ *     hotspotRegions: [
+ *       { uid: "r1", shape: "circle", coords: [50, 40, 8], isCorrect: true, label: "Heart" },
+ *     ],
+ *   }}
+ *   onAnswer={(answers) => handleAnswer(answers)}
+ * />
+ */
+export const Hotspot = memo(function Hotspot({
+  question,
+  sessionAnswers,
+  onAnswer,
+  readOnly = false,
+  showCorrectAnswers = false,
+  disabled = false,
+}: QuestionProps) {
+  const multiSelect = question.hotspotMultiSelect ?? false;
+
+  const [selected, setSelected] = useState<Set<string>>(() => {
+    const set = new Set<string>();
+    for (const sa of sessionAnswers ?? []) {
+      set.add(sa.answerUid);
+    }
+    return set;
+  });
+
+  const regions = useMemo(
+    () => question.hotspotRegions ?? [],
+    [question.hotspotRegions],
+  );
+
+  const handleClick = (regionUid: string) => {
+    if (readOnly || disabled) return;
+
+    let next: Set<string>;
+    if (multiSelect) {
+      next = new Set(selected);
+      if (next.has(regionUid)) {
+        next.delete(regionUid);
+      } else {
+        next.add(regionUid);
+      }
+    } else {
+      next = selected.has(regionUid) ? new Set() : new Set([regionUid]);
+    }
+
+    setSelected(next);
+    onAnswer?.([...next].map((uid) => ({ uid })));
+  };
+
+  const getRegionClasses = (region: HotspotRegion) => {
+    const isSelected = selected.has(region.uid);
+
+    if (showCorrectAnswers) {
+      if (region.isCorrect && isSelected) {
+        return "ring-3 ring-success bg-success/20 border-2 border-success";
+      }
+      if (region.isCorrect && !isSelected) {
+        return "ring-2 ring-success/50 border-2 border-dashed border-success/50";
+      }
+      if (!region.isCorrect && isSelected) {
+        return "ring-3 ring-destructive bg-destructive/20 border-2 border-destructive";
+      }
+      return "";
+    }
+
+    if (isSelected) {
+      return "ring-3 ring-primary bg-primary/20 border-2 border-primary";
+    }
+
+    return "hover:bg-primary/10";
+  };
+
+  return (
+    <div className="flex flex-col gap-4">
+      <div dangerouslySetInnerHTML={{ __html: question.content }} />
+
+      <div className="relative inline-block max-w-full">
+        {question.hotspotImageUrl && (
+          <img
+            src={question.hotspotImageUrl}
+            alt="Hotspot question image"
+            className="w-full h-auto rounded-md"
+            draggable={false}
+          />
+        )}
+
+        {regions.map((region, i) => (
+          <button
+            key={region.uid}
+            type="button"
+            onClick={() => handleClick(region.uid)}
+            disabled={readOnly || disabled}
+            aria-label={region.label || `Region ${i + 1}`}
+            aria-pressed={selected.has(region.uid)}
+            className={cn(
+              "absolute transition-all cursor-pointer",
+              "disabled:cursor-default",
+              "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary",
+              getRegionClasses(region),
+            )}
+            style={getRegionStyle(region)}
+          />
+        ))}
+      </div>
+
+      {showCorrectAnswers && question.explanation && (
+        <Alert className="mt-2">
+          <AlertDescription>
+            <strong>Explanation:</strong>{" "}
+            <span dangerouslySetInnerHTML={{ __html: question.explanation }} />
+          </AlertDescription>
+        </Alert>
+      )}
+    </div>
+  );
+});

package/src/questions/index.ts

@@ -4,11 +4,29 @@ export { Choice } from "./choice";
 export { TrueFalse } from "./true-false";
 export { FillInTheBlank } from "./fill-in-the-blank";
 export { Essay } from "./essay";
+export { Numeric } from "./numeric";
+export { Ordering } from "./ordering";
+export { Matching } from "./matching";
+export { Hotspot } from "./hotspot";
+export { InlineChoice } from "./inline-choice";
+export { Scenario } from "./scenario";
+export { Spreadsheet } from "./spreadsheet";
+export { scoreQuestion, scoreScenarioSubQuestions } from "./scoring";
+export { ConfidenceIndicator } from "./confidence-indicator";
+export type { ConfidenceIndicatorProps, ConfidenceLevel } from "./confidence-indicator";
 
 export type {
   QuestionProps,
   QuestionData,
   QuestionTypeEnum,
+  QuestionMaterial,
   AnswerOption,
   SessionAnswer,
+  MatchingPair,
+  HotspotRegion,
+  InlineBlank,
+  ScenarioScoringMode,
+  SpreadsheetColumn,
+  SpreadsheetCell,
+  SpreadsheetRow,
 } from "./types";