@hydralms/components 0.2.0 → 0.3.0

package/src/license/validate.ts

@@ -0,0 +1,90 @@
+// ─── Shared License Validation ──────────────────────────────
+
+const CACHE_KEY = 'hydra_key_v';
+const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+
+export type KeyResult = 'valid-pro' | 'valid-free' | 'invalid' | 'no-key' | 'skip';
+
+export interface ValidationResponse {
+  valid: boolean;
+  plan: 'pro' | 'enterprise' | null;
+}
+
+/** Read a cached validation result from sessionStorage. */
+function readCache(rawKey: string): KeyResult | null {
+  try {
+    const cached = sessionStorage.getItem(CACHE_KEY);
+    if (cached) {
+      const { result, ts, key } = JSON.parse(cached) as { result: KeyResult; ts: number; key: string };
+      if (key === rawKey && Date.now() - ts < CACHE_TTL) return result;
+    }
+  } catch { /* sessionStorage unavailable */ }
+  return null;
+}
+
+/** Write a validation result to sessionStorage cache. */
+function writeCache(rawKey: string, result: KeyResult): void {
+  try {
+    sessionStorage.setItem(CACHE_KEY, JSON.stringify({ result, ts: Date.now(), key: rawKey }));
+  } catch { /* full or unavailable */ }
+}
+
+/** On network failure, trust a previously cached valid-pro result. */
+function fallbackFromCache(rawKey: string): KeyResult {
+  try {
+    const cached = sessionStorage.getItem(CACHE_KEY);
+    if (cached) {
+      const { result, key } = JSON.parse(cached) as { result: KeyResult; key: string };
+      if (key === rawKey && result === 'valid-pro') return 'valid-pro';
+    }
+  } catch { /* ignore */ }
+  return 'invalid';
+}
+
+/**
+ * Validate a license key against the validation endpoint.
+ * @param rawKey - The license key string, or null if not provided.
+ * @param validateUrl - The validation endpoint URL. Empty string skips validation (dev mode).
+ */
+export async function validateKey(rawKey: string | null, validateUrl: string): Promise<KeyResult> {
+  // No validation URL configured (local dev) — skip entirely
+  if (!validateUrl) return 'skip';
+
+  // No key provided
+  if (!rawKey) return 'no-key';
+
+  // Check sessionStorage cache
+  const cached = readCache(rawKey);
+  if (cached) return cached;
+
+  // Network validation
+  try {
+    const res = await fetch(`${validateUrl}?key=${encodeURIComponent(rawKey)}`, {
+      method: 'GET',
+      signal: AbortSignal.timeout(4000),
+    });
+
+    if (!res.ok) return fallbackFromCache(rawKey);
+
+    const data = await res.json() as ValidationResponse;
+    let result: KeyResult;
+
+    if (!data.valid) {
+      result = 'invalid';
+    } else if (data.plan === 'pro' || data.plan === 'enterprise') {
+      result = 'valid-pro';
+    } else {
+      result = 'valid-free';
+    }
+
+    writeCache(rawKey, result);
+    return result;
+  } catch {
+    return fallbackFromCache(rawKey);
+  }
+}
+
+/** Whether a watermark should be shown for the given key result. */
+export function shouldShowWatermark(result: KeyResult): boolean {
+  return result === 'no-key' || result === 'invalid' || result === 'valid-free';
+}

package/src/license/withProGate.tsx

@@ -0,0 +1,21 @@
+import React from 'react';
+import { useHydraLicense } from './useHydraLicense';
+import { ProBadge } from './ProBadge';
+
+/** Higher-order component that wraps a pro-tier module with ProBadge when unlicensed. */
+export function withProGate<P extends object>(
+  Component: React.ComponentType<P>,
+  moduleName: string,
+) {
+  const Gated = (props: P) => {
+    const { isPro } = useHydraLicense();
+    if (isPro) return <Component {...props} />;
+    return (
+      <ProBadge feature={moduleName}>
+        <Component {...props} />
+      </ProBadge>
+    );
+  };
+  Gated.displayName = `ProGated(${moduleName})`;
+  return Gated;
+}

package/src/modules/AssignmentModule/AssignmentModule.tsx

@@ -20,6 +20,7 @@ import { Alert, AlertDescription } from "../../ui/alert";
 import { Separator } from "../../ui/separator";
 import { cn } from "../../lib/utils";
 import type { SubmissionData } from "../../sections/AssignmentSubmission/types";
+import { withProGate } from "../../license/withProGate";
 import type { AssignmentModuleProps } from "./types";
 
 type InternalStep =
@@ -39,19 +40,21 @@ const TYPE_LABELS: Record<string, string> = {
  *
  * Steps: Instructions → Work (AssignmentSubmission) → Confirmation.
  */
-export function AssignmentModule({
+function AssignmentModuleBase({
   title,
   instructions,
   dueDate,
   maxScore,
-  submissionTypes,
+  submissionTypes = ["text", "file"],
   fileConstraints,
   rubric,
   existingSubmission,
   status = "not_started",
   grade,
   onSubmit,
+  onComplete,
   onSaveDraft,
+  readOnly = false,
   className,
   style,
 }: AssignmentModuleProps) {
@@ -71,7 +74,7 @@ export function AssignmentModule({
   }, [step.tag]);
 
   const rubricMaxScore = useMemo(() => {
-    if (!rubric) return 0;
+    if (!Array.isArray(rubric)) return 0;
     return rubric.reduce(
       (sum, c) => sum + Math.max(...c.levels.map((l) => l.points)),
       0
@@ -80,11 +83,13 @@ export function AssignmentModule({
 
   function handleSubmit(submission: SubmissionData) {
     onSubmit?.(submission);
+    onComplete?.({ submission, status: "submitted" });
     setStep({ tag: "confirmation", submission });
   }
 
   function handleSaveDraft(submission: SubmissionData) {
     onSaveDraft?.(submission);
+    onComplete?.({ submission, status: "draft" });
   }
 
   const canEdit =
@@ -138,7 +143,7 @@ export function AssignmentModule({
             </div>
 
             {/* Rubric preview */}
-            {rubric && rubric.length > 0 && (
+            {Array.isArray(rubric) && rubric.length > 0 && (
               <>
                 <Separator className="my-6" />
                 <RubricView
@@ -149,11 +154,12 @@ export function AssignmentModule({
             )}
 
             {/* Action */}
-            {canEdit && (
+            {canEdit && !readOnly && (
               <div className="text-center mt-8">
                 <Button
                   size="lg"
                   onClick={() => setStep({ tag: "work" })}
+                  disabled={readOnly}
                 >
                   <Play className="size-4 mr-2" />
                   Start Assignment
@@ -196,6 +202,7 @@ export function AssignmentModule({
           grade={grade}
           onSubmit={handleSubmit}
           onSaveDraft={handleSaveDraft}
+          readOnly={readOnly}
         />
       </div>
     );
@@ -243,7 +250,7 @@ export function AssignmentModule({
                   <AlertDescription>{grade.feedback}</AlertDescription>
                 </Alert>
               )}
-              {rubric && grade.rubricLevels && (
+              {Array.isArray(rubric) && grade.rubricLevels && (
                 <>
                   <Separator className="my-6" />
                   <RubricView
@@ -266,7 +273,7 @@ export function AssignmentModule({
             {submission.textContent && (
               <div className="flex items-start gap-2">
                 <FileText className="size-4 mt-0.5 shrink-0" />
-                <span className="line-clamp-2">{submission.textContent}</span>
+                <span className="line-clamp-2">{submission.textContent.replace(/<[^>]*>/g, "")}</span>
               </div>
             )}
             {submission.files && submission.files.length > 0 && (
@@ -287,7 +294,7 @@ export function AssignmentModule({
           </div>
 
           {/* Edit button */}
-          {canEdit && (
+          {canEdit && !readOnly && (
             <div className="text-center mt-8">
               <Button
                 variant="outline"
@@ -303,3 +310,5 @@ export function AssignmentModule({
     </div>
   );
 }
+
+export const AssignmentModule = withProGate(AssignmentModuleBase, "AssignmentModule");

package/src/modules/AssignmentModule/types.ts

@@ -57,8 +57,12 @@ export interface AssignmentModuleProps {
   };
   /** Called on final submission */
   onSubmit?: (submission: SubmissionData) => void;
+  /** Called when the assignment is submitted or draft-saved, with the full result */
+  onComplete?: (result: AssignmentModuleResult) => void;
   /** Called on draft save */
   onSaveDraft?: (submission: SubmissionData) => void;
+  /** When true, disables interactions for preview/demo mode. @default false */
+  readOnly?: boolean;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */
@@ -69,5 +73,5 @@ export interface AssignmentModuleResult {
   /** The submitted data */
   submission: SubmissionData;
   /** Status after submission */
-  status: string;
+  status: "not_started" | "draft" | "submitted" | "late" | "graded" | "resubmit";
 }

package/src/modules/CertificateModule/CertificateModule.tsx

@@ -6,6 +6,7 @@ import { ProgressRing } from "../../progress/progress-ring";
 import { Button } from "../../ui/button";
 import { Card, CardContent } from "../../ui/card";
 import { cn } from "../../lib/utils";
+import { withProGate } from "../../license/withProGate";
 import type { CertificateModuleProps } from "./types";
 
 type InternalStep = { tag: "requirements" } | { tag: "certificate" };
@@ -17,7 +18,7 @@ type InternalStep = { tag: "requirements" } | { tag: "certificate" };
  * Steps: Requirements (checklist + progress) → Certificate (CertificateViewer).
  * The certificate step is only accessible when all requirements are completed.
  */
-export function CertificateModule({
+function CertificateModuleBase({
   courseTitle,
   recipientName,
   organizationName,
@@ -28,15 +29,20 @@ export function CertificateModule({
   requirements,
   overallProgress,
   onRequirementClick,
-  onCertificateEarned,
+  onComplete,
+  readOnly = false,
   className,
   style,
 }: CertificateModuleProps) {
-  const { allComplete, completedCount } = useMemo(() => {
+  const { allComplete, completedCount, derivedProgress } = useMemo(() => {
     const count = requirements.filter((r) => r.completed).length;
-    return { allComplete: count === requirements.length, completedCount: count };
+    const total = requirements.length;
+    const derived = total > 0 ? Math.round((count / total) * 100) : 0;
+    return { allComplete: count === total, completedCount: count, derivedProgress: derived };
   }, [requirements]);
 
+  const displayProgress = overallProgress ?? derivedProgress;
+
   const [step, setStep] = useState<InternalStep>({ tag: "requirements" });
   const contentRef = useRef<HTMLDivElement>(null);
   const earnedFiredRef = useRef(false);
@@ -45,13 +51,16 @@ export function CertificateModule({
     contentRef.current?.focus({ preventScroll: true });
   }, [step.tag]);
 
-  // Fire onCertificateEarned once when certificate step is first shown
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
+
+  // Fire onComplete once when certificate step is first shown
   useEffect(() => {
     if (step.tag === "certificate" && !earnedFiredRef.current) {
       earnedFiredRef.current = true;
-      onCertificateEarned?.();
+      onCompleteRef.current?.();
     }
-  }, [step.tag, onCertificateEarned]);
+  }, [step.tag]);
 
   // ─── Requirements Screen ───
   if (step.tag === "requirements") {
@@ -67,7 +76,7 @@ export function CertificateModule({
             {/* Header with progress */}
             <div className="text-center mb-6">
               <ProgressRing
-                value={overallProgress}
+                value={displayProgress}
                 size={100}
                 strokeWidth={8}
                 color={
@@ -88,7 +97,7 @@ export function CertificateModule({
             {/* Requirements checklist */}
             <RequirementsChecklist
               requirements={requirements}
-              onRequirementClick={onRequirementClick}
+              onRequirementClick={readOnly ? undefined : onRequirementClick}
               className="mb-6"
             />
 
@@ -98,6 +107,7 @@ export function CertificateModule({
                 <Button
                   size="lg"
                   onClick={() => setStep({ tag: "certificate" })}
+                  disabled={readOnly}
                 >
                   <Award className="size-4 mr-2" />
                   View Certificate
@@ -159,3 +169,5 @@ export function CertificateModule({
     </div>
   );
 }
+
+export const CertificateModule = withProGate(CertificateModuleBase, "CertificateModule");

package/src/modules/CertificateModule/types.ts

@@ -34,12 +34,14 @@ export interface CertificateModuleProps {
   certificateVariant?: CertificateVariant;
   /** Completion requirements */
   requirements: Requirement[];
-  /** Overall course progress (0-100) */
-  overallProgress: number;
+  /** Overall course progress (0-100). When omitted, derived from requirements completion. */
+  overallProgress?: number;
   /** Called when a requirement item is clicked */
   onRequirementClick?: (uid: string) => void;
-  /** Called when the certificate screen is first displayed */
-  onCertificateEarned?: () => void;
+  /** Called when the certificate is first displayed. @default undefined */
+  onComplete?: () => void;
+  /** When true, disables interactions for preview/demo mode. @default false */
+  readOnly?: boolean;
   /** CSS class name for the root element */
   className?: string;
   /** Inline styles for the root element */

package/src/modules/CourseCatalogModule/CourseCatalogModule.tsx

@@ -0,0 +1,126 @@
+import { useState, useRef, useEffect } from "react";
+import { ArrowLeft } from "lucide-react";
+import { CourseCatalog } from "../../sections/CourseCatalog/CourseCatalog";
+import { EnrollmentWizard } from "../../sections/EnrollmentWizard/EnrollmentWizard";
+import { Button } from "../../ui/button";
+import { Card, CardContent } from "../../ui/card";
+import { cn } from "../../lib/utils";
+import { withProGate } from "../../license/withProGate";
+import type { CourseCatalogModuleProps } from "./types";
+
+type InternalStep =
+  | { tag: "browse" }
+  | { tag: "enroll"; courseUid: string };
+
+/**
+ * CourseCatalogModule — a browse-and-enroll course catalog module.
+ *
+ * Master-detail layout: CourseCatalog (browse) ↔ EnrollmentWizard (enroll).
+ * Clicking a course drills into the enrollment flow; a back button returns to browsing.
+ */
+function CourseCatalogModuleBase({
+  title,
+  courses = [],
+  categories = [],
+  enrollmentData,
+  onEnroll,
+  onCourseOpen,
+  readOnly = false,
+  className,
+  style,
+}: CourseCatalogModuleProps) {
+  const [step, setStep] = useState<InternalStep>({ tag: "browse" });
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [step.tag]);
+
+  function handleCourseClick(courseUid: string) {
+    if (enrollmentData?.[courseUid]) {
+      setStep({ tag: "enroll", courseUid });
+    } else {
+      onCourseOpen?.(courseUid);
+    }
+  }
+
+  function handleBack() {
+    setStep({ tag: "browse" });
+  }
+
+  function handleEnrollConfirm(courseUid: string) {
+    onEnroll(courseUid);
+    setStep({ tag: "browse" });
+  }
+
+  return (
+    <div
+      ref={contentRef}
+      tabIndex={-1}
+      className={cn("outline-none", className)}
+      style={style}
+    >
+      {title && step.tag === "browse" && (
+        <h2 className="text-xl font-bold text-foreground mb-4">{title}</h2>
+      )}
+
+      {step.tag === "enroll" ? (
+        /* --- Enrollment View --- */
+        <div>
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={handleBack}
+            className="mb-4"
+          >
+            <ArrowLeft className="size-4 mr-1.5" />
+            Back to Catalog
+          </Button>
+          {enrollmentData?.[step.courseUid] ? (
+            <EnrollmentWizard
+              course={enrollmentData[step.courseUid].course}
+              prerequisites={enrollmentData[step.courseUid].prerequisites}
+              onEnroll={handleEnrollConfirm}
+              onCancel={handleBack}
+            />
+          ) : (
+            /* Fallback when enrollment data is not yet available */
+            <Card>
+              <CardContent className="pt-6">
+                <h3 className="text-lg font-semibold text-foreground mb-2">
+                  {courses.find((c) => c.uid === step.courseUid)?.title ??
+                    "Course"}
+                </h3>
+                <p className="text-sm text-muted-foreground mb-4">
+                  Enrollment details are loading. You can enroll directly below.
+                </p>
+                <div className="flex gap-2">
+                  <Button variant="outline" onClick={handleBack}>
+                    Cancel
+                  </Button>
+                  <Button
+                    onClick={() => handleEnrollConfirm(step.courseUid)}
+                    disabled={readOnly}
+                  >
+                    Enroll Now
+                  </Button>
+                </div>
+              </CardContent>
+            </Card>
+          )}
+        </div>
+      ) : (
+        /* --- Browse View --- */
+        <CourseCatalog
+          courses={courses}
+          categories={categories}
+          onCourseClick={(course) => handleCourseClick(course.uid)}
+          onEnroll={(course) => handleCourseClick(course.uid)}
+          readOnly={readOnly}
+        />
+      )}
+    </div>
+  );
+}
+
+export const CourseCatalogModule = withProGate(CourseCatalogModuleBase, "CourseCatalogModule");

package/src/modules/CourseCatalogModule/types.ts

@@ -0,0 +1,47 @@
+import type { CourseInfo } from "../../sections/CourseCatalog/types";
+import type {
+  EnrollmentCourse,
+  Prerequisite,
+} from "../../sections/EnrollmentWizard/types";
+
+/**
+ * CourseCatalogModule — a browse-and-enroll course catalog module.
+ *
+ * Master-detail layout: CourseCatalog (browse) ↔ EnrollmentWizard (enroll).
+ * Clicking a course drills into the enrollment flow; a back button returns to browsing.
+ *
+ * @example
+ * <CourseCatalogModule
+ *   title="Course Catalog"
+ *   courses={courses}
+ *   categories={categories}
+ *   enrollmentData={enrollmentData}
+ *   onEnroll={(courseUid) => handleEnroll(courseUid)}
+ * />
+ */
+export interface CourseCatalogModuleProps {
+  /** Catalog title */
+  title?: string;
+  /** Courses to display */
+  courses: CourseInfo[];
+  /** Optional categories for filtering */
+  categories?: { uid: string; label: string }[];
+  /** Enrollment data keyed by course UID — provides course details and prerequisites for the enrollment wizard */
+  enrollmentData?: Record<
+    string,
+    {
+      course: EnrollmentCourse;
+      prerequisites?: Prerequisite[];
+    }
+  >;
+  /** Called when a user confirms enrollment */
+  onEnroll: (courseUid: string) => void;
+  /** Called when a course is opened (for lazy-loading enrollment data) */
+  onCourseOpen?: (courseUid: string) => void;
+  /** When true, disables interactions for preview/demo mode. @default false */
+  readOnly?: boolean;
+  /** CSS class name for the root element */
+  className?: string;
+  /** Inline styles for the root element */
+  style?: React.CSSProperties;
+}

package/src/modules/CoursePlayer/CoursePlayer.tsx

@@ -1,4 +1,4 @@
-import { useState, useMemo, useRef, useEffect } from "react";
+import { useCallback, useState, useMemo, useRef, useEffect } from "react";
 import {
   ChevronLeft,
   ChevronRight,
@@ -23,9 +23,10 @@ import { Button } from "../../ui/button";
 import { flattenLeaves } from "../../utils/flatten-leaves";
 import { cn } from "../../lib/utils";
 import type { CurriculumItem } from "../../curriculum/types";
+import { withProGate } from "../../license/withProGate";
 import type { CoursePlayerProps, CoursePlayerItem } from "./types";
 
-export function CoursePlayer({
+function CoursePlayerBase({
   courseTitle,
   curriculum,
   progress,
@@ -71,33 +72,47 @@ export function CoursePlayer({
 
   const activeItem = itemMap.get(activeUid);
 
+  const videoConfig = useMemo(
+    () => activeItem?.type === "video"
+      ? { src: activeItem.src, poster: activeItem.poster, title: activeItem.title }
+      : null,
+    [activeItem],
+  );
+
   useEffect(() => {
     contentRef.current?.focus({ preventScroll: true });
   }, [activeUid]);
 
-  function navigateTo(uid: string) {
+  const onItemChangeRef = useRef(onItemChange);
+  onItemChangeRef.current = onItemChange;
+  const onItemCompleteRef = useRef(onItemComplete);
+  onItemCompleteRef.current = onItemComplete;
+
+  const navigateTo = useCallback((uid: string) => {
     setActiveUid(uid);
-    onItemChange?.(uid);
-  }
+    onItemChangeRef.current?.(uid);
+  }, []);
 
-  function handleItemClick(item: CurriculumItem) {
+  const handleItemClick = useCallback((item: CurriculumItem) => {
     if (!item.children || item.children.length === 0) {
       navigateTo(item.uid);
     }
-  }
+  }, [navigateTo]);
 
-  function handleMarkComplete() {
+  const handleMarkComplete = useCallback(() => {
     setCompletedUids((prev) => new Set(prev).add(activeUid));
-    onItemComplete?.(activeUid);
-  }
+    onItemCompleteRef.current?.(activeUid);
+  }, [activeUid]);
 
-  function handleNext() {
-    if (hasNext) navigateTo(leafUids[currentIndex + 1]);
-  }
+  const handleNext = useCallback(() => {
+    const idx = leafUids.indexOf(activeUid);
+    if (idx < leafUids.length - 1) navigateTo(leafUids[idx + 1]);
+  }, [leafUids, activeUid, navigateTo]);
 
-  function handlePrevious() {
-    if (hasPrevious) navigateTo(leafUids[currentIndex - 1]);
-  }
+  const handlePrevious = useCallback(() => {
+    const idx = leafUids.indexOf(activeUid);
+    if (idx > 0) navigateTo(leafUids[idx - 1]);
+  }, [leafUids, activeUid, navigateTo]);
 
   // Build combined progress for CourseOutline
   const combinedProgress = useMemo(() => {
@@ -169,7 +184,7 @@ export function CoursePlayer({
         {/* Content */}
         <div ref={contentRef} tabIndex={-1} className="flex-1 overflow-y-auto p-6 outline-none">
           {activeItem ? (
-            renderContent(activeItem, readOnly, handleMarkComplete, isCurrentCompleted, handleNext, hasNext, nextItem)
+            renderContent(activeItem, readOnly, handleMarkComplete, isCurrentCompleted, handleNext, hasNext, nextItem, videoConfig)
           ) : (
             <EmptyState
               title="No content selected"
@@ -233,6 +248,7 @@ function renderContent(
   onNext: () => void,
   hasNext: boolean,
   nextItem: CoursePlayerItem | null | undefined,
+  videoConfig: { src: string; poster?: string; title: string } | null,
 ) {
   switch (item.type) {
     case "lesson":
@@ -250,11 +266,8 @@ function renderContent(
     case "video":
       return (
         <LecturePlayer
-          video={{
-            src: item.src,
-            poster: item.poster,
-            title: item.title,
-          }}
+          video={videoConfig ?? { src: "", title: item.title }}
+          onComplete={isCompleted ? undefined : onMarkComplete}
         />
       );
     case "quiz":
@@ -275,3 +288,5 @@ function renderContent(
       );
   }
 }
+
+export const CoursePlayer = withProGate(CoursePlayerBase, "CoursePlayer");