@lessonkit/react 0.7.0 → 0.8.1

package/dist/index.js

@@ -12,7 +12,7 @@ import {
   useRef,
   useState
 } from "react";
-import { createTrackingClient } from "@lessonkit/core";
+import { createTrackingClient as createTrackingClient2 } from "@lessonkit/core";
 import { createInMemoryXAPIQueue } from "@lessonkit/xapi";
 import { telemetryEventToXAPIStatement as telemetryEventToXAPIStatement2 } from "@lessonkit/xapi";
 
@@ -55,7 +55,10 @@ function forwardTelemetryToLxpack(event, mode = "auto") {
       bridge.submitAssessment?.({
         id: data.checkId,
         score: scaled,
-        passingScore: normalizeAssessmentPassingScore(data.passingScore)
+        passingScore: normalizeAssessmentPassingScore({
+          passingScore: data.passingScore,
+          maxScore: data.maxScore
+        })
       });
       return;
     }
@@ -186,6 +189,12 @@ function createSessionStoragePort() {
         sessionStorage.setItem(key, value);
       } catch {
       }
+    },
+    removeItem: (key) => {
+      try {
+        sessionStorage.removeItem(key);
+      } catch {
+      }
     }
   };
 }
@@ -233,6 +242,8 @@ function createXapiClientFromConfig(config, queue) {
   if (config.xapi?.enabled === false) return null;
   if (config.xapi?.client) return config.xapi.client;
   if (!config.courseId) return null;
+  const hasTransport = typeof config.xapi?.transport === "function";
+  if (!hasTransport && config.xapi?.enabled !== true) return null;
   return createXAPIClient({
     courseId: config.courseId,
     transport: config.xapi?.transport,
@@ -243,6 +254,9 @@ function createXapiClientFromConfig(config, queue) {
 // src/runtime/session.ts
 import { createSessionId } from "@lessonkit/core";
 var SESSION_STORAGE_KEY = "lessonkit:sessionId";
+function getTabSessionId(storage) {
+  return storage.getItem(SESSION_STORAGE_KEY);
+}
 var COURSE_STARTED_PREFIX = "lessonkit:course_started:";
 function resolveSessionId(storage, provided) {
   if (provided) return provided;
@@ -263,30 +277,47 @@ function markCourseStarted(storage, sessionId, courseId) {
   if (!courseId) return;
   storage.setItem(courseStartedStorageKey(sessionId, courseId), "1");
 }
-
-// src/context.tsx
-import { jsx } from "react/jsx-runtime";
-var LessonkitContext = createContext(null);
-var useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
-function disposeTrackingClient(client) {
-  client?.flush?.();
-  client?.dispose?.();
+function migrateCourseStartedMark(storage, fromSessionId, toSessionId, courseId) {
+  if (!courseId || fromSessionId === toSessionId) return;
+  if (hasCourseStarted(storage, fromSessionId, courseId)) {
+    markCourseStarted(storage, toSessionId, courseId);
+    storage.removeItem?.(courseStartedStorageKey(fromSessionId, courseId));
+  }
 }
-var defaultStorage = createSessionStoragePort();
+
+// src/runtime/telemetry.ts
+import { createTrackingClient } from "@lessonkit/core";
 function createTrackingClientFromConfig(config) {
-  if (config.tracking?.enabled === false) {
-    return createTrackingClient();
-  }
+  if (config.tracking?.enabled === false) return createTrackingClient();
+  if (config.tracking?.createClient) return config.tracking.createClient();
   return createTrackingClient({
     sink: config.tracking?.sink,
     batchSink: config.tracking?.batchSink,
     batch: config.tracking?.batch
   });
 }
+function disposeTrackingClient(client) {
+  client?.flush?.();
+  client?.dispose?.();
+}
+
+// src/context.tsx
+import { jsx } from "react/jsx-runtime";
+var LessonkitContext = createContext(null);
+var useIsoLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+var defaultStorage = createSessionStoragePort();
+function isTrackingActive(tracking) {
+  return tracking?.enabled !== false;
+}
 function LessonkitProvider(props) {
   const config = props.config;
   const sessionIdRef = useRef(resolveSessionId(defaultStorage, config.session?.sessionId));
-  if (config.session?.sessionId) sessionIdRef.current = config.session.sessionId;
+  const prevConfiguredSessionIdRef = useRef(config.session?.sessionId);
+  if (config.session?.sessionId) {
+    sessionIdRef.current = config.session.sessionId;
+  } else if (prevConfiguredSessionIdRef.current) {
+    sessionIdRef.current = resolveSessionId(defaultStorage, void 0);
+  }
   const attemptIdRef = useRef(config.session?.attemptId);
   const userRef = useRef(config.session?.user);
   attemptIdRef.current = config.session?.attemptId;
@@ -296,6 +327,15 @@ function LessonkitProvider(props) {
   const lxpackBridgeModeRef = useRef(config.lxpack?.bridge ?? "auto");
   lxpackBridgeModeRef.current = config.lxpack?.bridge ?? "auto";
   const progressRef = useRef(createProgressController());
+  const courseStartedEmittedToSinkRef = useRef(false);
+  const prevCourseIdForProgressRef = useRef(config.courseId);
+  const pendingCourseIdResetRef = useRef(false);
+  if (prevCourseIdForProgressRef.current !== config.courseId) {
+    prevCourseIdForProgressRef.current = config.courseId;
+    progressRef.current = createProgressController();
+    pendingCourseIdResetRef.current = true;
+    courseStartedEmittedToSinkRef.current = false;
+  }
   const [progress, setProgress] = useState(() => progressRef.current.getState());
   const syncProgress = useCallback(() => {
     setProgress(progressRef.current.getState());
@@ -305,11 +345,16 @@ function LessonkitProvider(props) {
   const xapiQueueRef = useRef(createInMemoryXAPIQueue());
   const xapiRef = useRef(null);
   const [xapi, setXapi] = useState(null);
+  const prevXapiCourseIdRef = useRef(config.courseId);
   const xapiEnabled = config.xapi?.enabled;
   const xapiClient = config.xapi?.client;
   const xapiTransport = config.xapi?.transport;
   const courseId = config.courseId;
   useIsoLayoutEffect(() => {
+    if (prevXapiCourseIdRef.current !== courseId) {
+      xapiQueueRef.current = createInMemoryXAPIQueue();
+      prevXapiCourseIdRef.current = courseId;
+    }
     const prev = xapiRef.current;
     const next = createXapiClientFromConfig(config, xapiQueueRef.current);
     xapiRef.current = next;
@@ -317,22 +362,21 @@ function LessonkitProvider(props) {
     if (next && !prev) {
       const sessionId = sessionIdRef.current;
       const cid = courseIdRef.current;
-      if (hasCourseStarted(defaultStorage, sessionId, cid)) {
-        try {
-          const statement = telemetryEventToXAPIStatement2(
-            buildTrackEvent({
-              name: "course_started",
-              courseId: cid,
-              sessionId,
-              attemptId: attemptIdRef.current,
-              user: userRef.current
-            })
-          );
-          if (statement) next.send(statement);
-        } catch {
-        }
+      try {
+        const statement = telemetryEventToXAPIStatement2(
+          buildTrackEvent({
+            name: "course_started",
+            courseId: cid,
+            sessionId,
+            attemptId: attemptIdRef.current,
+            user: userRef.current
+          })
+        );
+        if (statement) next.send(statement);
+      } catch {
       }
     }
+    let cancelled = false;
     void (async () => {
       if (prev) {
         try {
@@ -340,16 +384,19 @@ function LessonkitProvider(props) {
         } catch {
         }
       }
+      if (cancelled) return;
       try {
         await next?.flush();
       } catch {
       }
     })();
     return () => {
+      cancelled = true;
       void prev?.flush();
     };
   }, [xapiEnabled, xapiClient, xapiTransport, courseId]);
-  const trackingRef = useRef(createTrackingClient());
+  const trackingRef = useRef(createTrackingClient2());
+  const trackingClientForUnmountRef = useRef(trackingRef.current);
   const [tracking, setTracking] = useState(() => trackingRef.current);
   const trackingEnabled = config.tracking?.enabled;
   const trackingSink = config.tracking?.sink;
@@ -359,12 +406,16 @@ function LessonkitProvider(props) {
   const batchMaxBatchSize = config.tracking?.batch?.maxBatchSize;
   useIsoLayoutEffect(() => {
     const prev = trackingRef.current;
-    const next = createTrackingClientFromConfig(config);
+    const next = createTrackingClientFromConfig({ tracking: config.tracking });
     trackingRef.current = next;
+    trackingClientForUnmountRef.current = next;
     setTracking(next);
     const sessionId = sessionIdRef.current;
     const cid = courseIdRef.current;
-    if (!hasCourseStarted(defaultStorage, sessionId, cid)) {
+    const trackingActive = isTrackingActive(config.tracking);
+    if (!trackingActive) {
+      courseStartedEmittedToSinkRef.current = false;
+    } else if (!courseStartedEmittedToSinkRef.current && !hasCourseStarted(defaultStorage, sessionId, cid)) {
       markCourseStarted(defaultStorage, sessionId, cid);
       emitTelemetry(
         next,
@@ -378,6 +429,9 @@ function LessonkitProvider(props) {
         }),
         { lxpackBridge: lxpackBridgeModeRef.current }
       );
+      courseStartedEmittedToSinkRef.current = true;
+    } else if (trackingActive) {
+      courseStartedEmittedToSinkRef.current = true;
     }
     return () => {
       if (prev !== trackingRef.current) {
@@ -416,21 +470,14 @@ function LessonkitProvider(props) {
     },
     [emitWithBridge]
   );
-  const prevCourseIdRef = useRef(config.courseId);
-  useEffect(() => {
-    if (prevCourseIdRef.current === config.courseId) return;
-    const previousActiveLesson = progressRef.current.getState().activeLessonId;
-    prevCourseIdRef.current = config.courseId;
-    progressRef.current = createProgressController();
+  useLayoutEffect(() => {
+    if (!pendingCourseIdResetRef.current) return;
+    pendingCourseIdResetRef.current = false;
     syncProgress();
-    if (previousActiveLesson) {
-      progressRef.current.setActiveLesson(previousActiveLesson, Date.now());
-      syncProgress();
-      track("lesson_started", { lessonId: previousActiveLesson }, { lessonId: previousActiveLesson });
-    }
+    if (!isTrackingActive(config.tracking)) return;
     const sessionId = sessionIdRef.current;
-    const cid = config.courseId;
-    if (!hasCourseStarted(defaultStorage, sessionId, cid)) {
+    const cid = courseIdRef.current;
+    if (!courseStartedEmittedToSinkRef.current && !hasCourseStarted(defaultStorage, sessionId, cid)) {
       markCourseStarted(defaultStorage, sessionId, cid);
       emitTelemetry(
         trackingRef.current,
@@ -444,8 +491,9 @@ function LessonkitProvider(props) {
         }),
         { lxpackBridge: lxpackBridgeModeRef.current }
       );
+      courseStartedEmittedToSinkRef.current = true;
     }
-  }, [config.courseId, syncProgress, track]);
+  }, [config.courseId, config.tracking?.enabled, syncProgress]);
   const emitLessonCompleted = useCallback(
     (lessonId, durationMs) => {
       track("lesson_completed", { lessonId, durationMs }, { lessonId });
@@ -465,16 +513,21 @@ function LessonkitProvider(props) {
     },
     [syncProgress, emitLessonCompleted]
   );
+  const unmountTimerIdsRef = useRef([]);
   useEffect(() => {
     return () => {
-      const client = trackingRef.current;
+      for (const id of unmountTimerIdsRef.current) clearTimeout(id);
+      unmountTimerIdsRef.current = [];
+      const client = trackingClientForUnmountRef.current;
       void xapiRef.current?.flush();
-      setTimeout(() => {
+      const flushTimer = setTimeout(() => {
         client?.flush?.();
-        setTimeout(() => {
+        const disposeTimer = setTimeout(() => {
           client?.dispose?.();
         }, 0);
+        unmountTimerIdsRef.current.push(disposeTimer);
       }, 0);
+      unmountTimerIdsRef.current.push(flushTimer);
     };
   }, []);
   const setActiveLesson = useCallback(
@@ -499,10 +552,34 @@ function LessonkitProvider(props) {
     if (!result.didComplete) return;
     syncProgress();
     track("course_completed");
+    void trackingRef.current?.flush?.();
   }, [track, syncProgress]);
   const sessionUser = config.session?.user;
   const sessionAttemptId = config.session?.attemptId;
   const sessionConfiguredId = config.session?.sessionId;
+  useEffect(() => {
+    const nextConfigured = config.session?.sessionId;
+    const prevConfigured = prevConfiguredSessionIdRef.current;
+    if (nextConfigured === prevConfigured) return;
+    prevConfiguredSessionIdRef.current = nextConfigured;
+    const cid = courseIdRef.current;
+    if (nextConfigured) {
+      const fromIds = /* @__PURE__ */ new Set();
+      if (prevConfigured) fromIds.add(prevConfigured);
+      const tabId = getTabSessionId(defaultStorage);
+      if (tabId) fromIds.add(tabId);
+      for (const fromId of fromIds) {
+        if (fromId !== nextConfigured) {
+          migrateCourseStartedMark(defaultStorage, fromId, nextConfigured, cid);
+        }
+      }
+      sessionIdRef.current = nextConfigured;
+    } else if (prevConfigured) {
+      const nextAuto = resolveSessionId(defaultStorage, void 0);
+      migrateCourseStartedMark(defaultStorage, prevConfigured, nextAuto, cid);
+      sessionIdRef.current = nextAuto;
+    }
+  }, [sessionConfiguredId, config.courseId]);
   const runtime = useMemo(
     () => ({
       config,
@@ -655,6 +732,10 @@ function Quiz(props) {
   const [selected, setSelected] = useState2(null);
   const completedRef = useRef2(false);
   const questionId = useId();
+  useEffect2(() => {
+    completedRef.current = false;
+    setSelected(null);
+  }, [props.checkId, props.answer, props.question]);
   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: [
@@ -820,7 +901,195 @@ function useTheme() {
   }
   return ctx;
 }
+
+// src/blockCatalog.ts
+var blockCatalogVersion = 1;
+var BLOCK_CATALOG = [
+  {
+    type: "Course",
+    category: "container",
+    description: "Top-level course shell; wraps LessonkitProvider and emits course lifecycle telemetry.",
+    props: [
+      { name: "title", type: "string", required: true, description: "Course title shown in the h1." },
+      { name: "courseId", type: "CourseId", required: true, description: "Stable course identifier for telemetry and packaging." },
+      {
+        name: "config",
+        type: "Omit<LessonkitConfig, 'courseId'>",
+        required: false,
+        description: "Runtime config (tracking, xAPI, session, lxpack bridge). courseId is merged from props."
+      },
+      { name: "children", type: "ReactNode", required: true, description: "Lessons and course chrome." }
+    ],
+    requiredIds: ["courseId"],
+    a11y: {
+      element: "section",
+      ariaLabel: "title prop",
+      keyboard: "No block-specific keyboard behavior; focus flows to child content.",
+      notes: "Renders h1 with course title. Wrap with ThemeProvider at app root for theming."
+    },
+    theming: {
+      surface: "global-inherit",
+      stylingNotes: "Inherits --lk-* CSS variables from ThemeProvider on document or scoped host."
+    },
+    telemetry: {
+      emits: ["course_started", "course_completed"]
+    }
+  },
+  {
+    type: "Lesson",
+    category: "container",
+    description: "Lesson container; sets active lesson on mount and completes on unmount.",
+    props: [
+      { name: "title", type: "string", required: true, description: "Lesson title shown in the h2." },
+      { name: "lessonId", type: "LessonId", required: true, description: "Stable lesson identifier for telemetry and packaging." },
+      { name: "children", type: "ReactNode", required: true, description: "Scenario, Quiz, Reflection, and other blocks." }
+    ],
+    requiredIds: ["lessonId"],
+    parentConstraints: ["Course"],
+    a11y: {
+      element: "article",
+      ariaLabel: "title prop",
+      keyboard: "No block-specific keyboard behavior; focus flows to child content.",
+      notes: "Renders h2 with lesson title. Only one Lesson should be mounted as active at a time in typical SPA layouts."
+    },
+    theming: {
+      surface: "global-inherit",
+      stylingNotes: "Inherits --lk-* CSS variables from ThemeProvider."
+    },
+    telemetry: {
+      emits: ["lesson_started", "lesson_completed", "lesson_time_on_task"]
+    }
+  },
+  {
+    type: "Scenario",
+    category: "content",
+    description: "Scenario or narrative content region for branching stories and situational context.",
+    props: [
+      { name: "blockId", type: "BlockId", required: false, description: "Optional stable block id for interaction telemetry URNs." },
+      { name: "children", type: "ReactNode", required: true, description: "Scenario narrative and custom UI." }
+    ],
+    requiredIds: [],
+    optionalIds: ["blockId"],
+    parentConstraints: ["Lesson"],
+    a11y: {
+      element: "section",
+      ariaLabel: "Scenario",
+      keyboard: "No block-specific keyboard behavior; custom children may define their own.",
+      notes: "Use for situational framing. Pair with useTracking() for branching interactions."
+    },
+    theming: {
+      surface: "global-inherit",
+      dataAttributes: ["data-lk-block-id"],
+      stylingNotes: "Optional data-lk-block-id when blockId is set. Style via app CSS using --lk-* tokens."
+    },
+    telemetry: {
+      emits: [],
+      manualTracking: "useTracking().track('interaction', { kind, blockId, payload })"
+    }
+  },
+  {
+    type: "Reflection",
+    category: "content",
+    description: "Reflection prompt with a textarea for learner free-text responses.",
+    props: [
+      { name: "blockId", type: "BlockId", required: false, description: "Optional stable block id for interaction telemetry URNs." },
+      { name: "prompt", type: "string", required: false, description: "Reflection question or instruction." },
+      { name: "children", type: "ReactNode", required: false, description: "Optional content above the textarea." }
+    ],
+    requiredIds: [],
+    optionalIds: ["blockId"],
+    parentConstraints: ["Lesson"],
+    a11y: {
+      element: "section",
+      ariaLabel: "Reflection",
+      keyboard: "Textarea is keyboard-focusable; standard text entry.",
+      notes: "When prompt is set, textarea uses aria-labelledby; otherwise aria-label='Reflection response'."
+    },
+    theming: {
+      surface: "global-inherit",
+      dataAttributes: ["data-lk-block-id"],
+      stylingNotes: "Optional data-lk-block-id when blockId is set. Style textarea via app CSS."
+    },
+    telemetry: {
+      emits: [],
+      manualTracking: "useTracking().track('interaction', { kind, blockId, payload }) on submit or blur"
+    }
+  },
+  {
+    type: "Quiz",
+    aliases: ["KnowledgeCheck"],
+    category: "assessment",
+    description: "Single-question multiple-choice assessment with automatic answer and completion telemetry.",
+    props: [
+      { name: "checkId", type: "CheckId", required: true, description: "Stable check identifier for telemetry and LXPack assessments." },
+      { name: "question", type: "string", required: true, description: "Question text shown above choices." },
+      { name: "choices", type: "string[]", required: true, description: "Radio button choice labels." },
+      { name: "answer", type: "string", required: true, description: "Correct choice value (must match one choice)." }
+    ],
+    requiredIds: ["checkId"],
+    parentConstraints: ["Lesson"],
+    a11y: {
+      element: "section",
+      ariaLabel: "Quiz",
+      keyboard: "Radio group navigable with arrow keys; one choice per question.",
+      liveRegions: "role='status' aria-live='polite' for Correct / Try again feedback.",
+      notes: "Fieldset with visually hidden legend. KnowledgeCheck is an alias that renders Quiz with identical behavior."
+    },
+    theming: {
+      surface: "global-inherit",
+      dataAttributes: ["data-lk-check-id"],
+      stylingNotes: "data-lk-check-id set from checkId. Style labels and feedback via app CSS."
+    },
+    telemetry: {
+      emits: ["quiz_answered", "quiz_completed"],
+      requiresActiveLesson: true
+    }
+  },
+  {
+    type: "ProgressTracker",
+    category: "chrome",
+    description: "Displays count of completed lessons from runtime progress state.",
+    props: [],
+    requiredIds: [],
+    parentConstraints: ["Course"],
+    a11y: {
+      element: "aside",
+      ariaLabel: "Progress",
+      keyboard: "Presentational; no interactive elements.",
+      notes: "Shows 'Lessons completed: N' from progress.completedLessonIds."
+    },
+    theming: {
+      surface: "global-inherit",
+      stylingNotes: "Inherits --lk-* CSS variables; style via app CSS."
+    },
+    telemetry: {
+      emits: []
+    }
+  }
+];
+function buildBlockCatalog() {
+  return BLOCK_CATALOG.map((entry) => ({
+    ...entry,
+    props: entry.props.map((p) => ({ ...p })),
+    aliases: entry.aliases ? [...entry.aliases] : void 0,
+    optionalIds: entry.optionalIds ? [...entry.optionalIds] : void 0,
+    parentConstraints: entry.parentConstraints ? [...entry.parentConstraints] : void 0,
+    a11y: { ...entry.a11y },
+    theming: {
+      ...entry.theming,
+      dataAttributes: entry.theming.dataAttributes ? [...entry.theming.dataAttributes] : void 0
+    },
+    telemetry: {
+      ...entry.telemetry,
+      emits: [...entry.telemetry.emits]
+    }
+  }));
+}
+function getBlockCatalogEntry(type) {
+  return BLOCK_CATALOG.find((entry) => entry.type === type || entry.aliases?.includes(type));
+}
 export {
+  BLOCK_CATALOG,
   Course,
   KnowledgeCheck,
   Lesson,
@@ -830,6 +1099,9 @@ export {
   Reflection,
   Scenario,
   ThemeProvider,
+  blockCatalogVersion,
+  buildBlockCatalog,
+  getBlockCatalogEntry,
   useCompletion,
   useLessonkit,
   useProgress,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lessonkit/react",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "private": false,
   "description": "React components and hooks for building learning experiences with LessonKit.",
   "license": "Apache-2.0",
@@ -31,10 +31,14 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
-    }
+    },
+    "./block-catalog.v1.json": "./block-catalog.v1.json",
+    "./block-contract.v1.json": "./block-contract.v1.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "block-catalog.v1.json",
+    "block-contract.v1.json"
   ],
   "scripts": {
     "build": "tsup src/index.tsx --format esm,cjs --dts --external react --external react-dom --external @lessonkit/accessibility --external @lessonkit/lxpack --external @lessonkit/themes",
@@ -50,11 +54,11 @@
     "react-dom": ">=18"
   },
   "dependencies": {
-    "@lessonkit/accessibility": "0.7.0",
-    "@lessonkit/core": "0.7.0",
-    "@lessonkit/lxpack": "0.7.0",
-    "@lessonkit/themes": "0.7.0",
-    "@lessonkit/xapi": "0.7.0"
+    "@lessonkit/accessibility": "0.8.1",
+    "@lessonkit/core": "0.8.1",
+    "@lessonkit/lxpack": "0.8.1",
+    "@lessonkit/themes": "0.8.1",
+    "@lessonkit/xapi": "0.8.1"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",