@lessonkit/react 0.3.1 → 0.5.0

package/dist/index.js

@@ -12,8 +12,94 @@ import {
   useRef,
   useState
 } from "react";
-import { createTrackingClient, nowIso } from "@lessonkit/core";
-import { createInMemoryXAPIQueue, createXAPIClient } from "@lessonkit/xapi";
+import { createTrackingClient } from "@lessonkit/core";
+import { createInMemoryXAPIQueue } from "@lessonkit/xapi";
+
+// src/runtime/emitTelemetry.ts
+import { nowIso } from "@lessonkit/core";
+import { telemetryEventToXAPIStatement } from "@lessonkit/xapi";
+var warnedMissingCourseId = false;
+function isDevEnvironment() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function emitTelemetry(tracking, xapi, event) {
+  if (!event.courseId) {
+    if (isDevEnvironment() && !warnedMissingCourseId) {
+      warnedMissingCourseId = true;
+      console.warn("[lessonkit] telemetry event missing courseId");
+    }
+    return;
+  }
+  tracking.track(event);
+  try {
+    const statement = telemetryEventToXAPIStatement(event);
+    if (statement) xapi?.send(statement);
+  } catch (err) {
+    if (isDevEnvironment()) {
+      console.warn("[lessonkit] xAPI mapping skipped:", err instanceof Error ? err.message : err);
+    }
+  }
+}
+function buildTrackEvent(opts) {
+  const base = {
+    timestamp: nowIso(),
+    courseId: opts.courseId,
+    sessionId: opts.sessionId,
+    attemptId: opts.attemptId,
+    user: opts.user
+  };
+  switch (opts.name) {
+    case "course_started":
+      return { name: "course_started", ...base };
+    case "course_completed":
+      return { name: "course_completed", ...base };
+    case "lesson_started": {
+      const data = opts.data;
+      const lessonId = opts.lessonId ?? data?.lessonId;
+      if (!lessonId) throw new Error("lesson_started requires lessonId");
+      return {
+        name: "lesson_started",
+        ...base,
+        lessonId,
+        data: { lessonId, ...data }
+      };
+    }
+    case "lesson_completed":
+    case "lesson_time_on_task": {
+      const data = opts.data;
+      const lessonId = opts.lessonId ?? data?.lessonId;
+      if (!lessonId) throw new Error(`${opts.name} requires lessonId`);
+      return {
+        name: opts.name,
+        ...base,
+        lessonId,
+        data: { lessonId, ...data }
+      };
+    }
+    case "quiz_answered": {
+      const data = opts.data;
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("quiz_answered requires active lessonId");
+      return { name: "quiz_answered", ...base, lessonId, data };
+    }
+    case "quiz_completed": {
+      const data = opts.data;
+      const lessonId = opts.lessonId;
+      if (!lessonId) throw new Error("quiz_completed requires active lessonId");
+      return { name: "quiz_completed", ...base, lessonId, data };
+    }
+    case "interaction":
+      return {
+        name: "interaction",
+        ...base,
+        lessonId: opts.lessonId,
+        data: opts.data
+      };
+    default:
+      return { name: opts.name, ...base };
+  }
+}
 
 // src/runtime/ports.ts
 function createNoopStorage() {
@@ -42,6 +128,53 @@ function createSessionStoragePort() {
   };
 }
 
+// src/runtime/progress.ts
+function createProgressController() {
+  let activeLessonId;
+  let completedLessonIds = /* @__PURE__ */ new Set();
+  let courseCompleted = false;
+  const lessonStartTimes = /* @__PURE__ */ new Map();
+  return {
+    getState: () => ({
+      activeLessonId,
+      completedLessonIds: new Set(completedLessonIds),
+      courseCompleted
+    }),
+    setActiveLesson: (lessonId, startedAtMs) => {
+      const previousLessonId = activeLessonId;
+      activeLessonId = lessonId;
+      lessonStartTimes.set(lessonId, startedAtMs);
+      return { previousLessonId };
+    },
+    completeLesson: (lessonId, completedAtMs) => {
+      if (completedLessonIds.has(lessonId)) return { didComplete: false };
+      completedLessonIds = new Set(completedLessonIds).add(lessonId);
+      const startedAt = lessonStartTimes.get(lessonId);
+      lessonStartTimes.delete(lessonId);
+      const durationMs = typeof startedAt === "number" ? Math.max(0, completedAtMs - startedAt) : void 0;
+      return { durationMs, didComplete: true };
+    },
+    completeCourse: () => {
+      if (courseCompleted) return { didComplete: false };
+      courseCompleted = true;
+      return { didComplete: true };
+    }
+  };
+}
+
+// src/runtime/xapi.ts
+import { createXAPIClient } from "@lessonkit/xapi";
+function createXapiClientFromConfig(config, queue) {
+  if (config.xapi?.enabled === false) return null;
+  if (config.xapi?.client) return config.xapi.client;
+  if (!config.courseId) return null;
+  return createXAPIClient({
+    courseId: config.courseId,
+    transport: config.xapi?.transport,
+    queue
+  });
+}
+
 // src/runtime/session.ts
 import { createSessionId } from "@lessonkit/core";
 var SESSION_STORAGE_KEY = "lessonkit:sessionId";
@@ -85,14 +218,8 @@ function createTrackingClientFromConfig(config) {
     batch: config.tracking?.batch
   });
 }
-function createXapiClientFromConfig(config, queue) {
-  if (config.xapi?.enabled === false) return null;
-  if (config.xapi?.client) return config.xapi.client;
-  const baseId = config.courseId ? `urn:lessonkit:course:${config.courseId}` : void 0;
-  return createXAPIClient({ baseId, transport: config.xapi?.transport, queue });
-}
 function LessonkitProvider(props) {
-  const config = props.config ?? {};
+  const config = props.config;
   const sessionIdRef = useRef(resolveSessionId(defaultStorage, config.session?.sessionId));
   if (config.session?.sessionId) sessionIdRef.current = config.session.sessionId;
   const attemptIdRef = useRef(config.session?.attemptId);
@@ -101,9 +228,15 @@ function LessonkitProvider(props) {
   userRef.current = config.session?.user;
   const courseIdRef = useRef(config.courseId);
   courseIdRef.current = config.courseId;
+  const progressRef = useRef(createProgressController());
+  const [progress, setProgress] = useState(() => progressRef.current.getState());
+  const syncProgress = useCallback(() => {
+    setProgress(progressRef.current.getState());
+  }, []);
+  const activeLessonIdRef = useRef(progress.activeLessonId);
+  activeLessonIdRef.current = progress.activeLessonId;
   const trackingRef = useRef(createTrackingClient());
   const [tracking, setTracking] = useState(() => trackingRef.current);
-  const courseStartedInProviderRef = useRef(false);
   const trackingEnabled = config.tracking?.enabled;
   const trackingSink = config.tracking?.sink;
   const trackingBatchSink = config.tracking?.batchSink;
@@ -117,21 +250,19 @@ function LessonkitProvider(props) {
     setTracking(next);
     const sessionId = sessionIdRef.current;
     const cid = courseIdRef.current;
-    const shouldEmitCourseStarted = cid ? !hasCourseStarted(defaultStorage, sessionId, cid) : !courseStartedInProviderRef.current;
-    if (shouldEmitCourseStarted) {
-      if (cid) {
-        markCourseStarted(defaultStorage, sessionId, cid);
-      } else {
-        courseStartedInProviderRef.current = true;
-      }
-      next.track({
-        name: "course_started",
-        timestamp: nowIso(),
-        courseId: cid,
-        sessionId,
-        attemptId: attemptIdRef.current,
-        user: userRef.current
-      });
+    if (!hasCourseStarted(defaultStorage, sessionId, cid)) {
+      markCourseStarted(defaultStorage, sessionId, cid);
+      emitTelemetry(
+        next,
+        xapiRef.current,
+        buildTrackEvent({
+          name: "course_started",
+          courseId: cid,
+          sessionId,
+          attemptId: attemptIdRef.current,
+          user: userRef.current
+        })
+      );
     }
     return () => {
       disposeTrackingClient(prev);
@@ -172,21 +303,10 @@ function LessonkitProvider(props) {
       void prev?.flush();
     };
   }, [xapiEnabled, xapiClient, xapiTransport, courseId]);
-  const [completedLessonIds, setCompletedLessonIds] = useState(() => /* @__PURE__ */ new Set());
-  const completedLessonIdsRef = useRef(completedLessonIds);
-  completedLessonIdsRef.current = completedLessonIds;
-  const [activeLessonId, setActiveLessonId] = useState(void 0);
-  const [courseCompleted, setCourseCompleted] = useState(false);
-  const courseCompletedRef = useRef(false);
-  courseCompletedRef.current = courseCompleted;
-  const activeLessonIdRef = useRef(void 0);
-  activeLessonIdRef.current = activeLessonId;
-  const lessonStartTimesRef = useRef(/* @__PURE__ */ new Map());
   const track = useCallback(
     (name, data, opts) => {
-      trackingRef.current?.track({
+      const event = buildTrackEvent({
         name,
-        timestamp: nowIso(),
         courseId: courseIdRef.current,
         lessonId: opts?.lessonId ?? activeLessonIdRef.current,
         sessionId: sessionIdRef.current,
@@ -194,6 +314,7 @@ function LessonkitProvider(props) {
         user: userRef.current,
         data
       });
+      emitTelemetry(trackingRef.current, xapiRef.current, event);
     },
     []
   );
@@ -203,45 +324,47 @@ function LessonkitProvider(props) {
       void xapiRef.current?.flush();
     };
   }, []);
-  const setActiveLesson = useCallback((lessonId) => {
-    if (activeLessonIdRef.current === lessonId) return;
-    activeLessonIdRef.current = lessonId;
-    setActiveLessonId(lessonId);
-    lessonStartTimesRef.current.set(lessonId, Date.now());
-    track("lesson_started", { lessonId }, { lessonId });
-    xapiRef.current?.startedLesson({ lessonId });
-  }, [track]);
-  const completeLesson = useCallback(
-    (lessonId) => {
-      if (completedLessonIdsRef.current.has(lessonId)) return;
-      completedLessonIdsRef.current = new Set(completedLessonIdsRef.current).add(lessonId);
-      setCompletedLessonIds(completedLessonIdsRef.current);
-      const startedAt = lessonStartTimesRef.current.get(lessonId);
-      lessonStartTimesRef.current.delete(lessonId);
-      const durationMs = typeof startedAt === "number" ? Math.max(0, Date.now() - startedAt) : void 0;
+  const emitLessonCompleted = useCallback(
+    (lessonId, durationMs) => {
       track("lesson_completed", { lessonId, durationMs }, { lessonId });
       if (durationMs !== void 0) {
         track("lesson_time_on_task", { lessonId, durationMs }, { lessonId });
       }
-      xapiRef.current?.completeLesson({ lessonId, durationMs });
     },
     [track]
   );
+  const completeLesson = useCallback(
+    (lessonId) => {
+      const result = progressRef.current.completeLesson(lessonId, Date.now());
+      if (!result.didComplete) return;
+      syncProgress();
+      emitLessonCompleted(lessonId, result.durationMs);
+    },
+    [syncProgress, emitLessonCompleted]
+  );
+  const setActiveLesson = useCallback(
+    (lessonId) => {
+      const current = progressRef.current.getState();
+      if (current.activeLessonId === lessonId) return;
+      const previous = current.activeLessonId;
+      if (previous && previous !== lessonId) {
+        const completed = progressRef.current.completeLesson(previous, Date.now());
+        if (completed.didComplete) {
+          emitLessonCompleted(previous, completed.durationMs);
+        }
+      }
+      progressRef.current.setActiveLesson(lessonId, Date.now());
+      syncProgress();
+      track("lesson_started", { lessonId }, { lessonId });
+    },
+    [track, syncProgress, emitLessonCompleted]
+  );
   const completeCourse = useCallback(() => {
-    if (courseCompletedRef.current) return;
-    courseCompletedRef.current = true;
-    setCourseCompleted(true);
+    const result = progressRef.current.completeCourse();
+    if (!result.didComplete) return;
+    syncProgress();
     track("course_completed");
-    xapiRef.current?.completeCourse();
-  }, [track]);
-  const progress = useMemo(
-    () => ({
-      activeLessonId,
-      completedLessonIds: new Set(completedLessonIds),
-      courseCompleted
-    }),
-    [activeLessonId, completedLessonIds, courseCompleted]
-  );
+  }, [track, syncProgress]);
   const runtime = useMemo(
     () => ({
       config,
@@ -293,9 +416,28 @@ function useQuizState() {
   );
 }
 
+// src/runtime/validateComponentId.ts
+import { validateId } from "@lessonkit/core";
+var warnedPaths = /* @__PURE__ */ new Set();
+function isDevEnvironment2() {
+  const g = globalThis;
+  return typeof g.process !== "undefined" && g.process.env?.NODE_ENV !== "production";
+}
+function warnInvalidComponentId(id, path) {
+  if (!isDevEnvironment2()) return;
+  const key = `${path}:${String(id)}`;
+  if (warnedPaths.has(key)) return;
+  const result = validateId(id, path);
+  if (result.ok) return;
+  warnedPaths.add(key);
+  const detail = result.issues.map((i) => `${i.path}: ${i.message}`).join("; ");
+  console.warn(`[lessonkit] invalid ${path} \u2014 ${detail}`);
+}
+
 // src/components.tsx
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
 function Course(props) {
+  warnInvalidComponentId(props.courseId, "courseId");
   const providerConfig = useMemo3(
     () => ({ ...props.config, courseId: props.courseId }),
     [props.config, props.courseId]
@@ -306,15 +448,23 @@ function Course(props) {
   ] }) });
 }
 function Lesson(props) {
+  warnInvalidComponentId(props.lessonId, "lessonId");
   const { setActiveLesson } = useLessonkit();
   const { completeLesson } = useCompletion();
-  const reactId = useId();
-  const generatedId = useMemo3(() => `lesson-${sanitizeLessonId(reactId)}`, [reactId]);
-  const id = props.lessonId ?? generatedId;
+  const id = props.lessonId;
+  const pendingCompleteRef = useRef2(null);
   useEffect2(() => {
+    if (pendingCompleteRef.current !== null) {
+      clearTimeout(pendingCompleteRef.current);
+      pendingCompleteRef.current = null;
+    }
     setActiveLesson(id);
     return () => {
-      completeLesson(id);
+      const lessonId = id;
+      pendingCompleteRef.current = setTimeout(() => {
+        pendingCompleteRef.current = null;
+        completeLesson(lessonId);
+      }, 0);
     };
   }, [id, setActiveLesson, completeLesson]);
   return /* @__PURE__ */ jsxs("article", { "aria-label": props.title, children: [
@@ -323,11 +473,13 @@ function Lesson(props) {
   ] });
 }
 function Scenario(props) {
-  return /* @__PURE__ */ jsx2("section", { "aria-label": "Scenario", children: props.children });
+  if (props.blockId !== void 0) warnInvalidComponentId(props.blockId, "blockId");
+  return /* @__PURE__ */ jsx2("section", { "aria-label": "Scenario", "data-lk-block-id": props.blockId, children: props.children });
 }
 function Reflection(props) {
+  if (props.blockId !== void 0) warnInvalidComponentId(props.blockId, "blockId");
   const promptId = useId();
-  return /* @__PURE__ */ jsxs("section", { "aria-label": "Reflection", children: [
+  return /* @__PURE__ */ jsxs("section", { "aria-label": "Reflection", "data-lk-block-id": props.blockId, children: [
     props.prompt ? /* @__PURE__ */ jsx2("p", { id: promptId, children: props.prompt }) : null,
     props.children,
     /* @__PURE__ */ jsx2(
@@ -340,14 +492,23 @@ function Reflection(props) {
   ] });
 }
 function KnowledgeCheck(props) {
-  return /* @__PURE__ */ jsx2(Quiz, { question: props.question, choices: props.choices, answer: props.answer });
+  return /* @__PURE__ */ jsx2(
+    Quiz,
+    {
+      checkId: props.checkId,
+      question: props.question,
+      choices: props.choices,
+      answer: props.answer
+    }
+  );
 }
 function Quiz(props) {
+  warnInvalidComponentId(props.checkId, "checkId");
   const quiz = useQuizState();
   const [selected, setSelected] = useState2(null);
   const completedRef = useRef2(false);
   const questionId = useId();
-  return /* @__PURE__ */ jsxs("section", { "aria-label": "Quiz", children: [
+  return /* @__PURE__ */ jsxs("section", { "aria-label": "Quiz", "data-lk-check-id": props.checkId, children: [
     /* @__PURE__ */ jsx2("p", { id: questionId, children: props.question }),
     /* @__PURE__ */ jsxs("fieldset", { "aria-labelledby": questionId, children: [
       /* @__PURE__ */ jsx2("legend", { style: visuallyHiddenStyle, children: "Quiz choices" }),
@@ -362,10 +523,15 @@ function Quiz(props) {
             onChange: () => {
               setSelected(c);
               const correct = c === props.answer;
-              quiz.answer({ question: props.question, choice: c, correct });
+              quiz.answer({
+                checkId: props.checkId,
+                question: props.question,
+                choice: c,
+                correct
+              });
               if (correct && !completedRef.current) {
                 completedRef.current = true;
-                quiz.complete({ score: 1, maxScore: 1 });
+                quiz.complete({ checkId: props.checkId, score: 1, maxScore: 1 });
               }
             }
           }
@@ -384,9 +550,128 @@ function ProgressTracker() {
     completed
   ] }) });
 }
-function sanitizeLessonId(id) {
-  const s = id.replace(/[^a-zA-Z0-9_-]/g, "");
-  return s.length ? s : "id";
+
+// src/theme/ThemeProvider.tsx
+import React3, {
+  createContext as createContext2,
+  useCallback as useCallback2,
+  useContext as useContext2,
+  useLayoutEffect as useLayoutEffect2,
+  useMemo as useMemo4,
+  useRef as useRef3,
+  useState as useState3
+} from "react";
+import {
+  brandThemeOverrides,
+  darkTheme,
+  getPresetTheme,
+  lightTheme,
+  mergeThemes,
+  themeToCssVariables
+} from "@lessonkit/themes";
+
+// src/theme/applyCssVariables.ts
+function applyCssVariables(target, vars, previousKeys) {
+  for (const key of previousKeys) {
+    if (!(key in vars)) {
+      target.style.removeProperty(key);
+    }
+  }
+  const nextKeys = /* @__PURE__ */ new Set();
+  for (const [key, value] of Object.entries(vars)) {
+    target.style.setProperty(key, value);
+    nextKeys.add(key);
+  }
+  return nextKeys;
+}
+
+// src/theme/ThemeProvider.tsx
+import { jsx as jsx3 } from "react/jsx-runtime";
+var ThemeContext = createContext2(null);
+var useIsoLayoutEffect2 = typeof window !== "undefined" ? useLayoutEffect2 : React3.useEffect;
+function getSystemMode() {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return "light";
+  }
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+function resolveModeBase(mode, resolvedMode) {
+  if (mode === "system") {
+    return resolvedMode === "dark" ? darkTheme : lightTheme;
+  }
+  if (mode === "dark") return darkTheme;
+  return lightTheme;
+}
+function ThemeProvider(props) {
+  const preset = props.preset ?? "default";
+  const mode = props.mode ?? "light";
+  const targetKind = props.target ?? "document";
+  const [resolvedMode, setResolvedMode] = useState3(
+    () => mode === "system" ? getSystemMode() : mode
+  );
+  useIsoLayoutEffect2(() => {
+    if (mode !== "system") {
+      setResolvedMode(mode);
+      return;
+    }
+    setResolvedMode(getSystemMode());
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const onChange = () => setResolvedMode(mq.matches ? "dark" : "light");
+    mq.addEventListener("change", onChange);
+    return () => mq.removeEventListener("change", onChange);
+  }, [mode]);
+  const dataTheme = mode === "system" ? resolvedMode : mode === "dark" ? "dark" : "light";
+  const effectiveTheme = useMemo4(() => {
+    const modeBase = resolveModeBase(mode, dataTheme);
+    const base = preset === "default" ? modeBase : preset === "brand" ? mergeThemes(modeBase, brandThemeOverrides) : mergeThemes(modeBase, getPresetTheme(preset));
+    return mergeThemes(base, props.theme ?? {});
+  }, [preset, mode, dataTheme, props.theme]);
+  const hostRef = useRef3(null);
+  const appliedKeysRef = useRef3(/* @__PURE__ */ new Set());
+  useIsoLayoutEffect2(() => {
+    if (targetKind === "document" && typeof document !== "undefined") {
+      document.documentElement.setAttribute("data-lk-theme", dataTheme);
+      return () => document.documentElement.removeAttribute("data-lk-theme");
+    }
+  }, [targetKind, dataTheme]);
+  const inject = useCallback2(() => {
+    const vars = themeToCssVariables(effectiveTheme);
+    const el = targetKind === "document" && typeof document !== "undefined" ? document.documentElement : hostRef.current;
+    if (!el) return;
+    appliedKeysRef.current = applyCssVariables(el, vars, appliedKeysRef.current);
+  }, [effectiveTheme, targetKind]);
+  useIsoLayoutEffect2(() => {
+    inject();
+    return () => {
+      const el = targetKind === "document" && typeof document !== "undefined" ? document.documentElement : hostRef.current;
+      if (!el) return;
+      for (const key of appliedKeysRef.current) {
+        el.style.removeProperty(key);
+      }
+      appliedKeysRef.current = /* @__PURE__ */ new Set();
+    };
+  }, [inject, targetKind]);
+  const value = useMemo4(
+    () => ({
+      theme: effectiveTheme,
+      preset,
+      mode,
+      resolvedMode: dataTheme
+    }),
+    [effectiveTheme, preset, mode, dataTheme]
+  );
+  if (targetKind === "document") {
+    return /* @__PURE__ */ jsx3(ThemeContext.Provider, { value, children: /* @__PURE__ */ jsx3("div", { "data-lk-theme": dataTheme, style: { display: "contents" }, children: props.children }) });
+  }
+  return /* @__PURE__ */ jsx3(ThemeContext.Provider, { value, children: /* @__PURE__ */ jsx3("div", { ref: hostRef, "data-lk-theme": dataTheme, children: props.children }) });
+}
+function useTheme() {
+  const ctx = useContext2(ThemeContext);
+  if (!ctx) {
+    throw new Error("useTheme must be used within a ThemeProvider");
+  }
+  return ctx;
 }
 export {
   Course,
@@ -397,9 +682,11 @@ export {
   Quiz,
   Reflection,
   Scenario,
+  ThemeProvider,
   useCompletion,
   useLessonkit,
   useProgress,
   useQuizState,
+  useTheme,
   useTracking
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/react",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "private": false,
   "description": "React components and hooks for building learning experiences with LessonKit.",
   "license": "Apache-2.0",
@@ -37,8 +37,8 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup src/index.tsx --format esm,cjs --dts --external react --external react-dom --external @lessonkit/accessibility",
-    "dev": "tsup src/index.tsx --format esm,cjs --dts --watch --external react --external react-dom --external @lessonkit/accessibility",
+    "build": "tsup src/index.tsx --format esm,cjs --dts --external react --external react-dom --external @lessonkit/accessibility --external @lessonkit/themes",
+    "dev": "tsup src/index.tsx --format esm,cjs --dts --watch --external react --external react-dom --external @lessonkit/accessibility --external @lessonkit/themes",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
     "test": "vitest run --passWithNoTests",
@@ -50,9 +50,10 @@
     "react-dom": ">=18"
   },
   "dependencies": {
-    "@lessonkit/accessibility": "0.3.1",
-    "@lessonkit/core": "0.3.1",
-    "@lessonkit/xapi": "0.3.1"
+    "@lessonkit/accessibility": "0.5.0",
+    "@lessonkit/core": "0.5.0",
+    "@lessonkit/themes": "0.5.0",
+    "@lessonkit/xapi": "0.5.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",