@hydralms/components 0.3.0 → 0.3.1

package/src/sections/AdaptiveLearningPath/types.ts

@@ -0,0 +1,159 @@
+import type { ReactNode } from "react";
+
+/**
+ * Status of a single node in the learning path.
+ * - `locked` — prerequisites not met, node is inaccessible
+ * - `available` — prerequisites met, learner can start
+ * - `in_progress` — learner is currently working on this node
+ * - `completed` — learner finished but below mastery threshold
+ * - `mastered` — learner finished and reached the mastery threshold
+ * - `skipped` — node was bypassed by the adaptive engine
+ */
+export type PathNodeStatus =
+  | "locked"
+  | "available"
+  | "in_progress"
+  | "completed"
+  | "mastered"
+  | "skipped";
+
+/**
+ * The type of learning activity a path node represents.
+ * Aligns with LearningObjectIcon type strings.
+ */
+export type PathNodeType =
+  | "lesson"
+  | "quiz"
+  | "assignment"
+  | "video"
+  | "discussion"
+  | "document"
+  | "assessment"
+  | "audio"
+  | "link";
+
+/** A skill or competency area that the learning path develops. */
+export interface PathSkill {
+  uid: string;
+  name: string;
+  /** Current proficiency level 0–100 */
+  proficiency: number;
+  /** Target proficiency level 0–100 */
+  targetProficiency?: number;
+}
+
+/** A milestone marker along the learning path. */
+export interface PathMilestone {
+  uid: string;
+  title: string;
+  description?: string;
+  /** Whether the milestone has been reached */
+  reached: boolean;
+  /** Index of the node after which this milestone appears (zero-based) */
+  afterNodeIndex: number;
+  variant?: "default" | "gold" | "silver" | "bronze";
+}
+
+/** A single node in the adaptive learning path. */
+export interface PathNode {
+  uid: string;
+  title: string;
+  description?: string;
+  /** Learning activity type — used for icon selection via LearningObjectIcon */
+  type: PathNodeType;
+  status: PathNodeStatus;
+  /** Estimated duration in seconds */
+  estimatedDuration?: number;
+  /** Performance score if completed (0–100) */
+  score?: number;
+  /** Whether this node is recommended as the next step */
+  recommended?: boolean;
+  /** Skill UIDs that this node develops */
+  skillUids?: string[];
+  /** UIDs of prerequisite nodes */
+  prerequisites?: string[];
+  /** Optional custom icon (overrides type-based icon) */
+  icon?: ReactNode;
+}
+
+/** A branch point where the adaptive engine may redirect the learner. */
+export interface PathBranch {
+  uid: string;
+  /** UID of the node where the branch originates */
+  fromNodeUid: string;
+  /** Label for this branch (e.g., "Review Fundamentals") */
+  label: string;
+  /** UIDs of nodes in this branch path */
+  nodeUids: string[];
+  /** Whether this branch is the active/chosen branch */
+  active?: boolean;
+  /** Condition description (e.g., "Score below 70%") */
+  condition?: string;
+}
+
+/** Overall progress summary for the path. */
+export interface PathProgress {
+  /** Percentage of path completed (0–100) */
+  completionPercentage: number;
+  completedNodes: number;
+  totalNodes: number;
+  /** Total time spent in seconds */
+  totalTimeSpent: number;
+  /** Average score across completed nodes (0–100) */
+  averageScore?: number;
+  /** Current streak in days */
+  currentStreak?: number;
+}
+
+/**
+ * AdaptiveLearningPath section — a premium visualization of a personalized
+ * learning sequence that adapts based on learner performance.
+ *
+ * Shows a visual path map with nodes, connectors, milestones, skill bars,
+ * and summary stats. Each node represents a learning activity with status,
+ * score, and recommended-next indicators.
+ *
+ * @example
+ * <AdaptiveLearningPath
+ *   title="React Mastery Path"
+ *   description="A personalized journey for mastering React"
+ *   nodes={pathNodes}
+ *   progress={pathProgress}
+ *   onNodeClick={(uid) => navigate(`/activity/${uid}`)}
+ *   onNodeStart={(uid) => startActivity(uid)}
+ * />
+ */
+export interface AdaptiveLearningPathProps {
+  /** Path title */
+  title: string;
+  /** Optional path description */
+  description?: string;
+  /** Difficulty level displayed in the header */
+  difficulty?: "beginner" | "intermediate" | "advanced";
+  /** Ordered list of learning path nodes */
+  nodes: PathNode[];
+  /** Overall path progress data */
+  progress: PathProgress;
+  /** Skill/competency areas covered by this path */
+  skills?: PathSkill[];
+  /** Milestones along the path */
+  milestones?: PathMilestone[];
+  /** Branch points for adaptive routing */
+  branches?: PathBranch[];
+  /** Called when the user clicks a node */
+  onNodeClick?: (nodeUid: string) => void;
+  /** Called when the user starts a recommended or available activity */
+  onNodeStart?: (nodeUid: string) => void;
+  /** Called when the user clicks a skill */
+  onSkillClick?: (skillUid: string) => void;
+  /** When true, disables all interactive elements. @default false */
+  readOnly?: boolean;
+  /** Render skeleton placeholders instead of content */
+  isLoading?: boolean;
+  /** Error message — renders an error state with optional retry */
+  error?: string | null;
+  /** Called when the user clicks retry in the error state */
+  onRetry?: () => void;
+  className?: string;
+  style?: React.CSSProperties;
+}

package/src/sections/ContentAuthoringStudio/ContentAuthoringStudio.tsx

@@ -0,0 +1,289 @@
+import { useState, useCallback, useMemo, useRef } from "react";
+import { Eye, Pencil, Save } from "lucide-react";
+import { Button } from "../../ui/button";
+import { Input } from "../../ui/input";
+import { Skeleton } from "../../ui/skeleton";
+import { ContentBlock } from "../../content";
+import { EmptyState } from "../../common/empty-state";
+import { SectionShell } from "../_shared/section-shell";
+import { useDragReorder } from "../../questions/use-drag-reorder";
+import { withProGate } from "../../license/withProGate";
+import type { LessonBlock } from "../../content/types";
+import type { ContentAuthoringStudioProps, AuthoringBlock } from "./types";
+import { BlockEditorItem } from "./block-editor-item";
+import { BlockTypePicker } from "./block-type-picker";
+
+let idCounter = 0;
+function genId() {
+  return `ab_${++idCounter}_${Date.now().toString(36)}`;
+}
+
+function toAuthoring(blocks: LessonBlock[]): AuthoringBlock[] {
+  return blocks.map((block) => ({ id: genId(), block }));
+}
+
+function createEmptyBlock(type: LessonBlock["type"]): LessonBlock {
+  switch (type) {
+    case "richtext":
+      return { type: "richtext", html: "" };
+    case "heading":
+      return { type: "heading", text: "", level: 2 };
+    case "image":
+      return { type: "image", src: "", alt: "" };
+    case "video":
+      return { type: "video", video: { src: "" } };
+    case "code":
+      return { type: "code", code: "", language: "javascript" };
+    case "callout":
+      return { type: "callout", content: "", variant: "info" };
+    case "audio":
+      return { type: "audio", src: "" };
+    case "embed":
+      return { type: "embed", src: "" };
+    case "table":
+      return { type: "table", headers: ["Column 1", "Column 2"], rows: [["", ""]] };
+    case "file":
+      return { type: "file", files: [] };
+    case "divider":
+      return { type: "divider" };
+    case "question":
+      return {
+        type: "question",
+        question: {
+          uid: genId(),
+          type: "multiple_choice",
+          content: "",
+          answers: [],
+        },
+      };
+    case "flashcards":
+      return { type: "flashcards", cards: [] };
+    case "custom":
+      return { type: "custom", render: null };
+    default:
+      return { type: "richtext", html: "" };
+  }
+}
+
+/**
+ * ContentAuthoringStudio — A premium block-based content editor for creating
+ * lessons. Produces `LessonBlock[]` compatible with `LessonPage`.
+ *
+ * Supports adding, editing, removing, reordering, and previewing content blocks
+ * including rich text, headings, images, videos, code, callouts, and more.
+ */
+function ContentAuthoringStudioBase({
+  title: titleProp = "",
+  blocks: blocksProp,
+  onBlocksChange,
+  onTitleChange,
+  onSave,
+  showPreviewToggle = true,
+  allowedBlockTypes,
+  readOnly = false,
+  isLoading,
+  error,
+  onRetry,
+  className,
+  style,
+}: ContentAuthoringStudioProps) {
+  const [title, setTitle] = useState(titleProp);
+  const [items, setItems] = useState<AuthoringBlock[]>(() =>
+    toAuthoring(blocksProp ?? []),
+  );
+  const [mode, setMode] = useState<"edit" | "preview">(readOnly ? "preview" : "edit");
+
+  const rawBlocks = useMemo(() => items.map((i) => i.block), [items]);
+
+  const emitChange = useCallback(
+    (nextItems: AuthoringBlock[]) => {
+      setItems(nextItems);
+      onBlocksChange?.(nextItems.map((i) => i.block));
+    },
+    [onBlocksChange],
+  );
+
+  /* ── Block operations ──────────────────────────── */
+
+  const itemsRef = useRef(items);
+  itemsRef.current = items;
+
+  function handleAddBlock(type: LessonBlock["type"], atIndex: number) {
+    const newItem: AuthoringBlock = { id: genId(), block: createEmptyBlock(type) };
+    const next = [...items];
+    next.splice(atIndex, 0, newItem);
+    emitChange(next);
+  }
+
+  const handleUpdateBlock = useCallback((id: string, block: LessonBlock) => {
+    emitChange(itemsRef.current.map((i) => (i.id === id ? { ...i, block } : i)));
+  }, [emitChange]);
+
+  const handleRemoveBlock = useCallback((id: string) => {
+    emitChange(itemsRef.current.filter((i) => i.id !== id));
+  }, [emitChange]);
+
+  const handleDuplicateBlock = useCallback((id: string) => {
+    const current = itemsRef.current;
+    const index = current.findIndex((i) => i.id === id);
+    if (index === -1) return;
+    const copy: AuthoringBlock = {
+      id: genId(),
+      block: structuredClone(current[index].block),
+    };
+    const next = [...current];
+    next.splice(index + 1, 0, copy);
+    emitChange(next);
+  }, [emitChange]);
+
+  const handleToggleCollapse = useCallback((id: string) => {
+    setItems((prev) =>
+      prev.map((i) =>
+        i.id === id ? { ...i, collapsed: !i.collapsed } : i,
+      ),
+    );
+  }, []);
+
+  function handleTitleChange(value: string) {
+    setTitle(value);
+    onTitleChange?.(value);
+  }
+
+  function handleSave() {
+    onSave?.({ title, blocks: rawBlocks });
+  }
+
+  /* ── Drag-and-drop ─────────────────────────────── */
+
+  const { getDragProps, dragIndex, dragOverIndex } = useDragReorder({
+    items,
+    onReorder: emitChange,
+    disabled: readOnly || mode === "preview",
+  });
+
+  /* ── Render ────────────────────────────────────── */
+
+  const isEditing = mode === "edit" && !readOnly;
+
+  return (
+    <SectionShell
+      isLoading={isLoading}
+      error={error}
+      onRetry={onRetry}
+      className={className}
+      style={style}
+      skeleton={
+        <>
+          <Skeleton className="h-10 w-64" />
+          <Skeleton className="h-6 w-32" />
+          <Skeleton className="h-32 w-full" />
+          <Skeleton className="h-24 w-full" />
+          <Skeleton className="h-32 w-full" />
+        </>
+      }
+    >
+      <div>
+        {/* Toolbar */}
+        <div className="flex items-center gap-2 mb-4">
+          {isEditing ? (
+            <Input
+              value={title}
+              onChange={(e) => handleTitleChange(e.target.value)}
+              placeholder="Lesson title..."
+              className="text-lg font-semibold flex-1 h-10"
+            />
+          ) : (
+            <h2 className="text-xl font-bold flex-1 text-foreground">{title || "Untitled Lesson"}</h2>
+          )}
+
+          {showPreviewToggle && !readOnly && (
+            <Button
+              variant="outline"
+              size="sm"
+              onClick={() => setMode(mode === "edit" ? "preview" : "edit")}
+              className="gap-1.5"
+            >
+              {mode === "edit" ? (
+                <>
+                  <Eye className="size-3.5" /> Preview
+                </>
+              ) : (
+                <>
+                  <Pencil className="size-3.5" /> Edit
+                </>
+              )}
+            </Button>
+          )}
+
+          {onSave && !readOnly && (
+            <Button size="sm" onClick={handleSave} className="gap-1.5">
+              <Save className="size-3.5" /> Save
+            </Button>
+          )}
+        </div>
+
+        {/* Content */}
+        {isEditing ? (
+          <div className="space-y-1">
+            {/* Top insertion point */}
+            <div className="flex justify-center py-1">
+              <BlockTypePicker
+                onSelect={(type) => handleAddBlock(type, 0)}
+                allowedTypes={allowedBlockTypes}
+              />
+            </div>
+
+            {items.length === 0 && (
+              <EmptyState
+                title="No content blocks"
+                description="Click 'Add block' above to start building your lesson."
+              />
+            )}
+
+            {items.map((item, index) => (
+              <div key={item.id}>
+                <BlockEditorItem
+                  item={item}
+                  onChange={handleUpdateBlock}
+                  onRemove={handleRemoveBlock}
+                  onDuplicate={handleDuplicateBlock}
+                  onToggleCollapse={handleToggleCollapse}
+                  dragProps={getDragProps(index)}
+                  isDragging={dragIndex === index}
+                  isDragOver={dragOverIndex === index}
+                />
+
+                {/* Insertion point after each block */}
+                <div className="flex justify-center py-1">
+                  <BlockTypePicker
+                    onSelect={(type) => handleAddBlock(type, index + 1)}
+                    allowedTypes={allowedBlockTypes}
+                  />
+                </div>
+              </div>
+            ))}
+          </div>
+        ) : (
+          /* Preview mode */
+          <div className="flex flex-col gap-3">
+            {items.length > 0 ? (
+              items.map((item) => (
+                <ContentBlock key={item.id} block={item.block} readOnly />
+              ))
+            ) : (
+              <EmptyState
+                title="No content yet"
+                description="Switch to edit mode to add content blocks."
+              />
+            )}
+          </div>
+        )}
+      </div>
+    </SectionShell>
+  );
+}
+
+export const ContentAuthoringStudio = withProGate(
+  ContentAuthoringStudioBase,
+  "ContentAuthoringStudio",
+);