@hydralms/components 0.2.0 → 0.3.0

package/src/progress/achievement-badge.tsx

@@ -5,9 +5,9 @@ import type { AchievementBadgeProps } from "./types";
 
 const VARIANT_STYLES = {
   default: "text-primary",
-  gold: "text-yellow-500",
-  silver: "text-gray-400",
-  bronze: "text-amber-700",
+  gold: "text-palette-3",
+  silver: "text-muted-foreground",
+  bronze: "text-palette-3/70",
 } as const;
 
 /**

package/src/progress/grade-indicator.tsx

@@ -36,7 +36,15 @@ export function GradeIndicator({
   if (variant === "linear") {
     return (
       <div className={cn("flex flex-row items-center gap-1", className)} style={style}>
-        <div className="flex-1 bg-muted rounded-full overflow-hidden" style={{ height: TRACK_HEIGHTS[size] }}>
+        <div
+          className="flex-1 bg-muted rounded-full overflow-hidden"
+          style={{ height: TRACK_HEIGHTS[size] }}
+          role="progressbar"
+          aria-valuenow={Math.round(percentage)}
+          aria-valuemin={0}
+          aria-valuemax={100}
+          aria-label={`Grade: ${letterGrade ?? `${Math.round(percentage)}%`}`}
+        >
           <div
             className="h-full rounded-full transition-[width] duration-300 ease-in-out"
             style={{ width: `${percentage}%`, background: color }}

package/src/progress/progress-ring.tsx

@@ -21,7 +21,7 @@ export function ProgressRing({
       className={cn("relative inline-flex", className)}
       style={{ width: `${size}px`, height: `${size}px`, ...style }}
     >
-      <svg width={size} height={size}>
+      <svg width={size} height={size} role="img" aria-label={label ?? `${Math.round(value)}% progress`}>
         <circle
           cx={center}
           cy={center}
@@ -48,6 +48,7 @@ export function ProgressRing({
       <span
         className="absolute inset-0 flex items-center justify-center font-bold text-foreground"
         style={{ fontSize: `${size * 0.2}px` }}
+        aria-hidden="true"
       >
         {label ?? `${Math.round(value)}%`}
       </span>

package/src/progress/stat-card.tsx

@@ -18,6 +18,7 @@ export const StatCard = memo(function StatCard({
   value,
   subtitle,
   trend,
+  accent,
   className,
   style,
 }: StatCardProps) {
@@ -27,7 +28,13 @@ export const StatCard = memo(function StatCard({
     <Card className={cn(className)} style={style}>
       <CardContent className="p-4">
         {icon && (
-          <div className="mb-2 w-9 h-9 rounded-lg bg-primary/10 flex items-center justify-center text-primary [&>svg]:size-5">
+          <div
+            className="mb-2 w-9 h-9 rounded-lg flex items-center justify-center [&>svg]:size-5"
+            style={{
+              backgroundColor: `color-mix(in oklch, ${accent ?? "var(--primary)"} 10%, transparent)`,
+              color: accent ?? "var(--primary)",
+            }}
+          >
             {icon}
           </div>
         )}

package/src/progress/types.ts

@@ -68,6 +68,8 @@ export interface StatCardProps {
   subtitle?: string;
   /** Optional trend data */
   trend?: { value: number; direction: "up" | "down" | "flat" };
+  /** Accent color CSS value for the icon background. Defaults to primary. */
+  accent?: string;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */

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, useMemo } 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,14 +12,14 @@ 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) => {
+}: QuestionProps) {
   const [selectedAnswer, setSelectedAnswer] = useState<string>(
     () => sessionAnswers?.[0]?.answerUid || "",
   );
@@ -53,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}
@@ -70,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">
@@ -85,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,4 +1,4 @@
-import { useState, useMemo, useRef } from "react";
+import { useState, useMemo, useRef, useEffect, memo } from "react";
 import { debounce } from "../utils/debounce";
 import { RichTextEditor } from "../ui/rich-text-editor";
 import type { QuestionProps } from "./types";
@@ -12,13 +12,13 @@ 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) => {
+}: QuestionProps) {
   const [value, setValue] = useState(() => sessionAnswers?.[0]?.content || "");
 
   const onAnswerRef = useRef(onAnswer);
@@ -33,6 +33,7 @@ export const Essay = ({
       }, 500),
     [],
   );
+  useEffect(() => () => debouncedAnswer.cancel(), [debouncedAnswer]);
 
   const handleChange = (html: string) => {
     setValue(html);
@@ -51,7 +52,8 @@ export const Essay = ({
         readOnly={readOnly}
         disabled={disabled}
         variant="default"
+        ariaLabel="Essay response"
       />
     </div>
   );
-};
+});

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

@@ -1,4 +1,4 @@
-import { useState, useMemo, useRef } 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,14 +13,15 @@ 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) => {
+}: QuestionProps) {
+  const inputId = useId();
   const [value, setValue] = useState(() => sessionAnswers?.[0]?.content || "");
 
   const onAnswerRef = useRef(onAnswer);
@@ -35,6 +36,7 @@ export const FillInTheBlank = ({
       }, 300),
     [],
   );
+  useEffect(() => () => debouncedAnswer.cancel(), [debouncedAnswer]);
 
   const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     const newValue = e.target.value;
@@ -46,7 +48,9 @@ export const FillInTheBlank = ({
     <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..."
@@ -63,4 +67,4 @@ export const FillInTheBlank = ({
       )}
     </div>
   );
-};
+});

package/src/questions/hotspot.tsx

@@ -1,4 +1,4 @@
-import { useState, useMemo } from "react";
+import { useState, useMemo, memo } from "react";
 import { Alert, AlertDescription } from "../ui/alert";
 import { cn } from "../lib/utils";
 import type { QuestionProps, HotspotRegion } from "./types";
@@ -43,14 +43,14 @@ function getRegionStyle(region: HotspotRegion): React.CSSProperties {
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const Hotspot = ({
+export const Hotspot = memo(function Hotspot({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
+}: QuestionProps) {
   const multiSelect = question.hotspotMultiSelect ?? false;
 
   const [selected, setSelected] = useState<Set<string>>(() => {
@@ -151,4 +151,4 @@ export const Hotspot = ({
       )}
     </div>
   );
-};
+});

package/src/questions/index.ts

@@ -12,6 +12,8 @@ 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,

package/src/questions/inline-choice.tsx

@@ -1,4 +1,4 @@
-import { useState, useMemo } from "react";
+import { useState, useMemo, memo } from "react";
 import { Alert, AlertDescription } from "../ui/alert";
 import { cn } from "../lib/utils";
 import type { QuestionProps, InlineBlank } from "./types";
@@ -44,14 +44,14 @@ function parseInlineContent(html: string): ContentPart[] {
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const InlineChoice = ({
+export const InlineChoice = memo(function InlineChoice({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
+}: QuestionProps) {
   const blanksMap = useMemo(() => {
     const map = new Map<string, InlineBlank>();
     for (const blank of question.inlineBlanks ?? []) {
@@ -118,6 +118,7 @@ export const InlineChoice = ({
           return (
             <select
               key={part.uid}
+              aria-label={`Blank ${blank.sequence + 1}`}
               value={selections.get(part.uid) || ""}
               onChange={(e) => handleSelect(part.uid, e.target.value)}
               disabled={readOnly || disabled}
@@ -148,4 +149,4 @@ export const InlineChoice = ({
       )}
     </div>
   );
-};
+});

package/src/questions/matching.tsx

@@ -1,4 +1,4 @@
-import { useState, useMemo, useCallback } from "react";
+import { useState, useMemo, useCallback, memo } from "react";
 import { Alert, AlertDescription } from "../ui/alert";
 import { cn } from "../lib/utils";
 import type { QuestionProps } from "./types";
@@ -23,14 +23,14 @@ import type { QuestionProps } from "./types";
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const Matching = ({
+export const Matching = memo(function Matching({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
+}: QuestionProps) {
   const sortedPairs = useMemo(
     () =>
       [...(question.matchingPairs ?? [])].sort(
@@ -158,6 +158,7 @@ export const Matching = ({
                   dangerouslySetInnerHTML={{ __html: pair.item }}
                 />
                 <select
+                  aria-label={`Match for: ${pair.item.replace(/<[^>]+>/g, "")}`}
                   value={matches.get(pair.uid) || ""}
                   onChange={(e) => handleSelect(pair.uid, e.target.value)}
                   disabled={readOnly || disabled}
@@ -225,4 +226,4 @@ export const Matching = ({
       )}
     </div>
   );
-};
+});

package/src/questions/multiple-choice.tsx

@@ -1,4 +1,4 @@
-import { useState, useMemo } 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,14 +12,14 @@ import { cn } from "../lib/utils";
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const MultipleChoice = ({
+export const MultipleChoice = memo(function MultipleChoice({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
+}: QuestionProps) {
   const [selectedAnswers, setSelectedAnswers] = useState<string[]>(
     () => sessionAnswers?.map((sa) => sa.answerUid) || [],
   );
@@ -59,7 +59,8 @@ export const MultipleChoice = ({
     <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">Select all correct answers</legend>
         {sortedAnswers.map((answer) => (
           <div
             key={answer.uid}
@@ -77,10 +78,16 @@ export const MultipleChoice = ({
                 className="text-sm"
                 dangerouslySetInnerHTML={{ __html: answer.content }}
               />
+              {showCorrectAnswers && answer.isCorrect && (
+                <span className="sr-only">(Correct answer)</span>
+              )}
+              {showCorrectAnswers && selectedAnswers.includes(answer.uid) && !answer.isCorrect && (
+                <span className="sr-only">(Your answer — incorrect)</span>
+              )}
             </label>
           </div>
         ))}
-      </div>
+      </fieldset>
 
       {showCorrectAnswers && question.explanation && (
         <Alert className="mt-2">
@@ -92,4 +99,4 @@ export const MultipleChoice = ({
       )}
     </div>
   );
-};
+});

package/src/questions/numeric.tsx

@@ -1,4 +1,4 @@
-import { useState, useMemo, useRef } 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";
@@ -14,14 +14,15 @@ import type { QuestionProps } from "./types";
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const Numeric = ({
+export const Numeric = memo(function Numeric({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
+}: QuestionProps) {
+  const inputId = useId();
   const [value, setValue] = useState(() => sessionAnswers?.[0]?.content || "");
 
   const onAnswerRef = useRef(onAnswer);
@@ -36,6 +37,7 @@ export const Numeric = ({
       }, 300),
     [],
   );
+  useEffect(() => () => debouncedAnswer.cancel(), [debouncedAnswer]);
 
   const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
     const newValue = e.target.value;
@@ -64,7 +66,9 @@ export const Numeric = ({
       <div dangerouslySetInnerHTML={{ __html: question.content }} />
 
       <div className="flex items-center gap-2">
+        <label htmlFor={inputId} className="sr-only">Numeric answer</label>
         <Input
+          id={inputId}
           type="number"
           value={value}
           onChange={handleChange}
@@ -99,4 +103,4 @@ export const Numeric = ({
       )}
     </div>
   );
-};
+});

package/src/questions/ordering.tsx

@@ -1,4 +1,4 @@
-import { useState, useMemo } from "react";
+import { useState, useMemo, memo } from "react";
 import { ChevronUp, ChevronDown, GripVertical } from "lucide-react";
 import { Alert, AlertDescription } from "../ui/alert";
 import { cn } from "../lib/utils";
@@ -15,20 +15,22 @@ import type { QuestionProps, AnswerOption } from "./types";
  *   onAnswer={(answers) => handleAnswer(answers)}
  * />
  */
-export const Ordering = ({
+export const Ordering = memo(function Ordering({
   question,
   sessionAnswers,
   onAnswer,
   readOnly = false,
   showCorrectAnswers = false,
   disabled = false,
-}: QuestionProps) => {
+}: QuestionProps) {
   const correctOrder = useMemo(
     () =>
       [...(question.answers || [])].sort((a, b) => a.sequence - b.sequence),
     [question.answers],
   );
 
+  const [announcement, setAnnouncement] = useState("");
+
   const [items, setItems] = useState<AnswerOption[]>(() => {
     if (sessionAnswers && sessionAnswers.length > 0) {
       // Rebuild order from sessionAnswers position indices
@@ -66,6 +68,9 @@ export const Ordering = ({
     next.splice(toIndex, 0, moved);
     setItems(next);
     emitAnswer(next);
+    setAnnouncement(
+      `${moved.content.replace(/<[^>]+>/g, "")} moved to position ${toIndex + 1} of ${items.length}`,
+    );
   };
 
   const { getDragProps, dragIndex, dragOverIndex } = useDragReorder({
@@ -85,6 +90,9 @@ export const Ordering = ({
   return (
     <div className="flex flex-col gap-4">
       <div dangerouslySetInnerHTML={{ __html: question.content }} />
+      <span className="sr-only" aria-live="assertive" role="status">
+        {announcement}
+      </span>
 
       <div className="flex flex-col gap-1.5">
         {items.map((item, index) => (
@@ -156,4 +164,4 @@ export const Ordering = ({
       )}
     </div>
   );
-};
+});

package/src/questions/question-renderer.tsx

@@ -1,3 +1,4 @@
+import { memo } from "react";
 import type { QuestionProps } from "./types";
 import { MultipleChoice } from "./multiple-choice";
 import { Choice } from "./choice";
@@ -22,7 +23,7 @@ import { Spreadsheet } from "./spreadsheet";
  *   onAnswer={handleAnswer}
  * />
  */
-export const QuestionRenderer = (props: QuestionProps) => {
+export const QuestionRenderer = memo(function QuestionRenderer(props: QuestionProps) {
   switch (props.question.type) {
     case "multiple_choice":
       return <MultipleChoice {...props} />;
@@ -55,4 +56,4 @@ export const QuestionRenderer = (props: QuestionProps) => {
         </p>
       );
   }
-};
+});