@hydralms/components 0.1.3 → 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

@@ -0,0 +1,314 @@
+import { useState, useRef, useEffect, useMemo } from "react";
+import {
+  FileEdit,
+  CheckCircle2,
+  Play,
+  ArrowLeft,
+  FileText,
+  Link as LinkIcon,
+  Paperclip,
+} from "lucide-react";
+import { AssignmentSubmission } from "../../sections/AssignmentSubmission/AssignmentSubmission";
+import { RubricView } from "../../sections/RubricView/RubricView";
+import { GradeIndicator } from "../../progress/grade-indicator";
+import { StatusBadge } from "../../common/status-badge";
+import { DueDateDisplay } from "../../common/due-date-display";
+import { Button } from "../../ui/button";
+import { Badge } from "../../ui/badge";
+import { Card, CardContent } from "../../ui/card";
+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 =
+  | { tag: "instructions" }
+  | { tag: "work" }
+  | { tag: "confirmation"; submission: SubmissionData };
+
+const TYPE_LABELS: Record<string, string> = {
+  text: "Text Entry",
+  file: "File Upload",
+  url: "URL Submission",
+};
+
+/**
+ * AssignmentModule — a complete assignment experience with instructions,
+ * submission work area, and confirmation/grade review.
+ *
+ * Steps: Instructions → Work (AssignmentSubmission) → Confirmation.
+ */
+function AssignmentModuleBase({
+  title,
+  instructions,
+  dueDate,
+  maxScore,
+  submissionTypes = ["text", "file"],
+  fileConstraints,
+  rubric,
+  existingSubmission,
+  status = "not_started",
+  grade,
+  onSubmit,
+  onComplete,
+  onSaveDraft,
+  readOnly = false,
+  className,
+  style,
+}: AssignmentModuleProps) {
+  const initialStep: InternalStep =
+    status === "submitted" || status === "graded"
+      ? {
+          tag: "confirmation",
+          submission: existingSubmission ?? {},
+        }
+      : { tag: "instructions" };
+
+  const [step, setStep] = useState<InternalStep>(initialStep);
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [step.tag]);
+
+  const rubricMaxScore = useMemo(() => {
+    if (!Array.isArray(rubric)) return 0;
+    return rubric.reduce(
+      (sum, c) => sum + Math.max(...c.levels.map((l) => l.points)),
+      0
+    );
+  }, [rubric]);
+
+  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 =
+    status === "not_started" ||
+    status === "draft" ||
+    status === "resubmit";
+
+  // ─── Instructions Screen ───
+  if (step.tag === "instructions") {
+    return (
+      <div
+        ref={contentRef}
+        tabIndex={-1}
+        className={cn("max-w-2xl mx-auto outline-none", className)}
+        style={style}
+      >
+        <Card>
+          <CardContent className="pt-8 pb-8">
+            <div className="text-center mb-6">
+              <div className="mx-auto mb-4 w-14 h-14 rounded-full bg-primary/10 flex items-center justify-center">
+                <FileEdit className="size-7 text-primary" />
+              </div>
+              <h2 className="text-2xl font-bold text-foreground mb-2">
+                {title}
+              </h2>
+            </div>
+
+            {/* Metadata chips */}
+            <div className="flex flex-wrap justify-center gap-2 mb-6">
+              {dueDate && (
+                <DueDateDisplay dueDate={dueDate} size="small" />
+              )}
+              {maxScore !== undefined && (
+                <Badge variant="outline" className="gap-1.5">
+                  <CheckCircle2 className="size-3.5" />
+                  {maxScore} points
+                </Badge>
+              )}
+              <Badge variant="outline" className="gap-1.5">
+                <Paperclip className="size-3.5" />
+                {submissionTypes.map((t) => TYPE_LABELS[t]).join(", ")}
+              </Badge>
+              <StatusBadge status={status} />
+            </div>
+
+            <Separator className="my-6" />
+
+            {/* Instructions content */}
+            <div className="prose prose-sm text-foreground mb-6">
+              {instructions}
+            </div>
+
+            {/* Rubric preview */}
+            {Array.isArray(rubric) && rubric.length > 0 && (
+              <>
+                <Separator className="my-6" />
+                <RubricView
+                  criteria={rubric}
+                  maxScore={rubricMaxScore}
+                />
+              </>
+            )}
+
+            {/* Action */}
+            {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
+                </Button>
+              </div>
+            )}
+          </CardContent>
+        </Card>
+      </div>
+    );
+  }
+
+  // ─── Work Screen ───
+  if (step.tag === "work") {
+    return (
+      <div
+        ref={contentRef}
+        tabIndex={-1}
+        className={cn("outline-none", className)}
+        style={style}
+      >
+        <Button
+          variant="ghost"
+          size="sm"
+          onClick={() => setStep({ tag: "instructions" })}
+          className="mb-4"
+        >
+          <ArrowLeft className="size-4 mr-1.5" />
+          Back to Instructions
+        </Button>
+        <AssignmentSubmission
+          title={title}
+          instructions={instructions}
+          dueDate={dueDate}
+          maxScore={maxScore}
+          status={status}
+          submissionTypes={submissionTypes}
+          existingSubmission={existingSubmission}
+          fileConstraints={fileConstraints}
+          grade={grade}
+          onSubmit={handleSubmit}
+          onSaveDraft={handleSaveDraft}
+          readOnly={readOnly}
+        />
+      </div>
+    );
+  }
+
+  // ─── Confirmation Screen ───
+  const { submission } = step;
+
+  return (
+    <div
+      ref={contentRef}
+      tabIndex={-1}
+      className={cn("max-w-2xl mx-auto outline-none", className)}
+      style={style}
+    >
+      <Card>
+        <CardContent className="pt-8 pb-8">
+          <div className="text-center mb-6">
+            <div className="mx-auto mb-4 w-14 h-14 rounded-full bg-success/10 flex items-center justify-center">
+              <CheckCircle2 className="size-7 text-success" />
+            </div>
+            <h2 className="text-xl font-bold text-foreground mb-2">
+              {status === "graded" ? "Assignment Graded" : "Submission Received"}
+            </h2>
+            <div className="flex justify-center gap-2 mb-4">
+              <StatusBadge status={status} />
+              {dueDate && <DueDateDisplay dueDate={dueDate} size="small" />}
+            </div>
+          </div>
+
+          {/* Grade display */}
+          {status === "graded" && grade && (
+            <div className="text-center mb-6">
+              <GradeIndicator
+                percentage={
+                  maxScore ? Math.round((grade.score / maxScore) * 100) : 0
+                }
+                size="large"
+              />
+              <p className="text-sm text-muted-foreground mt-2">
+                {grade.score}/{maxScore} points
+              </p>
+              {grade.feedback && (
+                <Alert className="text-left mt-4">
+                  <AlertDescription>{grade.feedback}</AlertDescription>
+                </Alert>
+              )}
+              {Array.isArray(rubric) && grade.rubricLevels && (
+                <>
+                  <Separator className="my-6" />
+                  <RubricView
+                    criteria={rubric}
+                    selectedLevels={grade.rubricLevels}
+                    totalScore={grade.score}
+                    maxScore={rubricMaxScore}
+                  />
+                </>
+              )}
+            </div>
+          )}
+
+          {/* Submission summary */}
+          <Separator className="my-6" />
+          <h3 className="text-sm font-semibold text-foreground mb-3">
+            What You Submitted
+          </h3>
+          <div className="space-y-2 text-sm text-muted-foreground">
+            {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.replace(/<[^>]*>/g, "")}</span>
+              </div>
+            )}
+            {submission.files && submission.files.length > 0 && (
+              <div className="flex items-start gap-2">
+                <Paperclip className="size-4 mt-0.5 shrink-0" />
+                <span>
+                  {submission.files.length} file
+                  {submission.files.length !== 1 ? "s" : ""} uploaded
+                </span>
+              </div>
+            )}
+            {submission.url && (
+              <div className="flex items-start gap-2">
+                <LinkIcon className="size-4 mt-0.5 shrink-0" />
+                <span className="truncate">{submission.url}</span>
+              </div>
+            )}
+          </div>
+
+          {/* Edit button */}
+          {canEdit && !readOnly && (
+            <div className="text-center mt-8">
+              <Button
+                variant="outline"
+                onClick={() => setStep({ tag: "work" })}
+              >
+                <FileEdit className="size-4 mr-2" />
+                Edit Submission
+              </Button>
+            </div>
+          )}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+export const AssignmentModule = withProGate(AssignmentModuleBase, "AssignmentModule");

package/src/modules/AssignmentModule/types.ts

@@ -0,0 +1,77 @@
+import type { ReactNode } from "react";
+import type { SubmissionData } from "../../sections/AssignmentSubmission/types";
+import type { RubricCriterion } from "../../sections/RubricView/types";
+
+/**
+ * AssignmentModule — a complete assignment experience with instructions,
+ * submission, and confirmation/grade review.
+ *
+ * Steps: Instructions → Work (AssignmentSubmission) → Confirmation.
+ * Optionally shows a grading rubric in both the instructions and
+ * graded confirmation views.
+ *
+ * @example
+ * <AssignmentModule
+ *   title="Week 3 Essay"
+ *   instructions={<p>Write a 500-word essay on React hooks.</p>}
+ *   submissionTypes={["text", "file"]}
+ *   rubric={rubricCriteria}
+ *   onSubmit={(submission) => submitAssignment(submission)}
+ * />
+ */
+export interface AssignmentModuleProps {
+  /** Assignment title */
+  title: string;
+  /** Assignment instructions (rich content) */
+  instructions: ReactNode;
+  /** Due date as ISO string */
+  dueDate?: string;
+  /** Maximum score points */
+  maxScore?: number;
+  /** Allowed submission types */
+  submissionTypes: ("text" | "file" | "url")[];
+  /** File upload constraints */
+  fileConstraints?: {
+    maxFiles?: number;
+    maxSizeMB?: number;
+    acceptedTypes?: string;
+  };
+  /** Rubric criteria for grading (shown in instructions and graded confirmation) */
+  rubric?: RubricCriterion[];
+  /** Existing submission for editing/viewing */
+  existingSubmission?: SubmissionData;
+  /** Current submission status. @default "not_started" */
+  status?:
+    | "not_started"
+    | "draft"
+    | "submitted"
+    | "late"
+    | "graded"
+    | "resubmit";
+  /** Grade data when graded */
+  grade?: {
+    score: number;
+    feedback?: ReactNode;
+    /** Selected rubric level UIDs per criterion UID */
+    rubricLevels?: Record<string, string>;
+  };
+  /** 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 */
+  style?: React.CSSProperties;
+}
+
+export interface AssignmentModuleResult {
+  /** The submitted data */
+  submission: SubmissionData;
+  /** Status after submission */
+  status: "not_started" | "draft" | "submitted" | "late" | "graded" | "resubmit";
+}

package/src/modules/CertificateModule/CertificateModule.tsx

@@ -0,0 +1,173 @@
+import { useState, useRef, useEffect, useMemo } from "react";
+import { Award, ArrowLeft, PartyPopper } from "lucide-react";
+import { RequirementsChecklist } from "../../sections/RequirementsChecklist/RequirementsChecklist";
+import { CertificateViewer } from "../../sections/CertificateViewer/CertificateViewer";
+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" };
+
+/**
+ * CertificateModule — a certificate-earning flow with requirements tracking
+ * and certificate display.
+ *
+ * Steps: Requirements (checklist + progress) → Certificate (CertificateViewer).
+ * The certificate step is only accessible when all requirements are completed.
+ */
+function CertificateModuleBase({
+  courseTitle,
+  recipientName,
+  organizationName,
+  organizationLogo,
+  signatory,
+  completionDate,
+  certificateVariant = "modern",
+  requirements,
+  overallProgress,
+  onRequirementClick,
+  onComplete,
+  readOnly = false,
+  className,
+  style,
+}: CertificateModuleProps) {
+  const { allComplete, completedCount, derivedProgress } = useMemo(() => {
+    const count = requirements.filter((r) => r.completed).length;
+    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);
+
+  useEffect(() => {
+    contentRef.current?.focus({ preventScroll: true });
+  }, [step.tag]);
+
+  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;
+      onCompleteRef.current?.();
+    }
+  }, [step.tag]);
+
+  // ─── Requirements Screen ───
+  if (step.tag === "requirements") {
+    return (
+      <div
+        ref={contentRef}
+        tabIndex={-1}
+        className={cn("max-w-2xl mx-auto outline-none", className)}
+        style={style}
+      >
+        <Card>
+          <CardContent className="pt-8 pb-8">
+            {/* Header with progress */}
+            <div className="text-center mb-6">
+              <ProgressRing
+                value={displayProgress}
+                size={100}
+                strokeWidth={8}
+                color={
+                  allComplete ? "var(--success)" : "var(--primary)"
+                }
+                className="mx-auto mb-4 text-foreground"
+              />
+              <h2 className="text-xl font-bold text-foreground mb-2">
+                {courseTitle}
+              </h2>
+              <p className="text-sm text-muted-foreground">
+                {allComplete
+                  ? "All requirements met — your certificate is ready!"
+                  : `${completedCount} of ${requirements.length} requirements complete`}
+              </p>
+            </div>
+
+            {/* Requirements checklist */}
+            <RequirementsChecklist
+              requirements={requirements}
+              onRequirementClick={readOnly ? undefined : onRequirementClick}
+              className="mb-6"
+            />
+
+            {/* View Certificate button */}
+            {allComplete && (
+              <div className="text-center mt-6">
+                <Button
+                  size="lg"
+                  onClick={() => setStep({ tag: "certificate" })}
+                  disabled={readOnly}
+                >
+                  <Award className="size-4 mr-2" />
+                  View Certificate
+                </Button>
+              </div>
+            )}
+          </CardContent>
+        </Card>
+      </div>
+    );
+  }
+
+  // ─── Certificate Screen ───
+  return (
+    <div
+      ref={contentRef}
+      tabIndex={-1}
+      className={cn("outline-none", className)}
+      style={style}
+    >
+      {/* Back link */}
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={() => setStep({ tag: "requirements" })}
+        className="mb-4"
+      >
+        <ArrowLeft className="size-4 mr-1.5" />
+        Back to Requirements
+      </Button>
+
+      {/* Congratulations header */}
+      <div className="text-center mb-8">
+        <div className="mx-auto mb-4 w-14 h-14 rounded-full bg-success/10 flex items-center justify-center">
+          <PartyPopper className="size-7 text-success" />
+        </div>
+        <h2 className="text-2xl font-bold text-foreground mb-2">
+          Congratulations!
+        </h2>
+        <p className="text-muted-foreground">
+          You&apos;ve completed all requirements for{" "}
+          <span className="font-medium text-foreground">{courseTitle}</span>
+        </p>
+      </div>
+
+      {/* Certificate */}
+      <CertificateViewer
+        recipientName={recipientName}
+        courseTitle={courseTitle}
+        completionDate={
+          completionDate ?? new Date().toISOString().split("T")[0]
+        }
+        organizationName={organizationName}
+        organizationLogo={organizationLogo}
+        signatory={signatory}
+        variant={certificateVariant}
+        showActions
+      />
+    </div>
+  );
+}
+
+export const CertificateModule = withProGate(CertificateModuleBase, "CertificateModule");