feat: add sequential progression and video watch lesson completion

Gate student content by completion order, track per-video watch progress with seek enforcement, and auto-complete lessons at the configured threshold. Show ring progress in the lesson header, keep watch progress on rewatch, and sync progression locks client-side so the next item unlocks after completion.
2026-06-11 14:48:34 +01:00
parent c8154409f5
commit 52d9bf18c3
94 changed files with 3499 additions and 564 deletions
@@ -11,3 +11,13 @@ export function parseCertificateThemeId(raw: string | null | undefined): Certifi

  return resolveTemplateId(raw);
 }
+
+/** Normalizes DB/API timestamps to an ISO-8601 UTC string accepted by Zod `.datetime()`. */
+export function normalizeCertificateIssuedAt(value: string | null | undefined): string {
+  if (!value) return new Date().toISOString();
+
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) return new Date().toISOString();
+
+  return parsed.toISOString();
+}
@@ -0,0 +1,36 @@
+import { ContentType } from '@cio/utils/constants/content';
+import type { Course } from './types';
+import { syncProgressionAccessToCourse } from './progression-utils';
+
+export function updateLessonCompletionInCourseContent(course: Course, lessonId: string, isComplete: boolean): Course {
+  if (!course.content) return course;
+
+  let updatedCourse: Course;
+
+  if (course.content.grouped) {
+    updatedCourse = {
+      ...course,
+      content: {
+        ...course.content,
+        sections: course.content.sections.map((section) => ({
+          ...section,
+          items: section.items.map((item) =>
+            item.type === ContentType.Lesson && item.id === lessonId ? { ...item, isComplete } : item
+          )
+        }))
+      }
+    };
+  } else {
+    updatedCourse = {
+      ...course,
+      content: {
+        ...course.content,
+        items: course.content.items.map((item) =>
+          item.type === ContentType.Lesson && item.id === lessonId ? { ...item, isComplete } : item
+        )
+      }
+    };
+  }
+
+  return syncProgressionAccessToCourse(updatedCourse);
+}
@@ -0,0 +1,25 @@
+import { ContentType } from '@cio/utils/constants/content';
+import type { StudentContentLockReason } from '$features/ai-assistant/utils/content-ask-ai-bar';
+
+export function getStudentContentLockTitleKey(reason: StudentContentLockReason): string {
+  if (reason === 'progression_locked') {
+    return 'course.navItem.lessons.content_progression_locked_title';
+  }
+
+  return 'course.navItem.lessons.content_locked_title';
+}
+
+export function getStudentContentLockDescriptionKey(
+  reason: StudentContentLockReason,
+  contentType: typeof ContentType.Lesson | typeof ContentType.Exercise
+): string {
+  if (reason === 'progression_locked') {
+    if (contentType === ContentType.Exercise) {
+      return 'course.navItem.lessons.content_progression_locked_description_exercise';
+    }
+
+    return 'course.navItem.lessons.content_progression_locked_description_lesson';
+  }
+
+  return 'course.navItem.lessons.content_locked_description';
+}
@@ -86,6 +86,8 @@ export function hydrateExercisePageData(exercise: Exercise, exerciseId: string)
    sectionDisplayMode: exercise.sectionDisplayMode ?? 'one_question',
    totalSubmissions: 0,
    allowMultipleAttempts: !!exercise.allowMultipleAttempts,
+    completionPolicy: (exercise.completionPolicy as 'submitted' | 'passed' | undefined) ?? 'submitted',
+    passThreshold: exercise.passThreshold ?? 100,
    slug: exercise.slug ?? ''
  });

@@ -0,0 +1,114 @@
+import { ContentType } from '@cio/utils/constants/content';
+import type { Course, CourseContentItem } from './types';
+
+type ProgressionLockReason = 'teacher_locked' | 'progression_blocked';
+
+function sortNavigableItems(items: CourseContentItem[]): CourseContentItem[] {
+  return [...items].sort((left, right) => {
+    const orderDiff = (left.order ?? 0) - (right.order ?? 0);
+    if (orderDiff !== 0) return orderDiff;
+
+    const typeDiff = (left.type === ContentType.Lesson ? 0 : 1) - (right.type === ContentType.Lesson ? 0 : 1);
+    if (typeDiff !== 0) return typeDiff;
+
+    return new Date(left.createdAt || 0).getTime() - new Date(right.createdAt || 0).getTime();
+  });
+}
+
+function getNavigableItems(course: Course): CourseContentItem[] {
+  if (!course.content) return [];
+
+  const items = course.content.grouped
+    ? course.content.sections.flatMap((section) => section.items)
+    : course.content.items;
+
+  return sortNavigableItems(
+    items.filter((item) => item.type === ContentType.Lesson || item.type === ContentType.Exercise)
+  );
+}
+
+function lessonBlocksProgression(policy: string | null | undefined): boolean {
+  return policy !== 'none';
+}
+
+function isItemProgressComplete(item: CourseContentItem): boolean {
+  return Boolean(item.isComplete);
+}
+
+function computeProgressionAccess(
+  navigableItems: CourseContentItem[],
+  progressionMode: 'free' | 'sequential'
+): Map<string, { accessible: boolean; lockReason: ProgressionLockReason | null }> {
+  const accessById = new Map<string, { accessible: boolean; lockReason: ProgressionLockReason | null }>();
+  let priorBlockingComplete = true;
+
+  for (const item of navigableItems) {
+    const teacherLocked = !(item.isUnlocked ?? false);
+    const progressionLocked = progressionMode === 'sequential' && !priorBlockingComplete;
+
+    let accessible = !teacherLocked && !progressionLocked;
+    let lockReason: ProgressionLockReason | null = null;
+
+    if (teacherLocked) {
+      accessible = false;
+      lockReason = 'teacher_locked';
+    } else if (progressionLocked) {
+      accessible = false;
+      lockReason = 'progression_blocked';
+    }
+
+    accessById.set(item.id, { accessible, lockReason });
+
+    const complete = isItemProgressComplete(item);
+    const blocks = item.type === ContentType.Lesson ? lessonBlocksProgression(item.completionPolicy ?? 'manual') : true;
+
+    if (blocks && !complete) {
+      priorBlockingComplete = false;
+    }
+  }
+
+  return accessById;
+}
+
+function annotateContentItem(
+  item: CourseContentItem,
+  accessById: Map<string, { accessible: boolean; lockReason: ProgressionLockReason | null }>
+): CourseContentItem {
+  const access = accessById.get(item.id);
+  if (!access) return item;
+
+  return {
+    ...item,
+    accessible: access.accessible,
+    lockReason: access.lockReason
+  };
+}
+
+/** Recomputes student progression locks on in-memory course content after completion changes. */
+export function syncProgressionAccessToCourse(course: Course): Course {
+  if (!course.content) return course;
+
+  const progressionMode = course.metadata?.progressionMode === 'sequential' ? 'sequential' : 'free';
+  const accessById = computeProgressionAccess(getNavigableItems(course), progressionMode);
+
+  if (course.content.grouped) {
+    return {
+      ...course,
+      content: {
+        ...course.content,
+        sections: course.content.sections.map((section) => ({
+          ...section,
+          items: section.items.map((item) => annotateContentItem(item, accessById))
+        }))
+      }
+    };
+  }
+
+  return {
+    ...course,
+    content: {
+      ...course.content,
+      items: course.content.items.map((item) => annotateContentItem(item, accessById))
+    }
+  };
+}
@@ -13,6 +13,7 @@ type CourseSettings = {
  lessonDownload: boolean;
  isPublished: boolean;
  isContentGroupingEnabled: boolean;
+  progressionMode: 'free' | 'sequential';
  callout: TCourseCallout | null;
 };

@@ -32,5 +33,6 @@ export const settings = writable<CourseSettings>({
  lessonDownload: false,
  isPublished: false,
  isContentGroupingEnabled: true,
+  progressionMode: 'free',
  callout: null
 });
@@ -126,6 +126,22 @@ export type UpdateLessonCompletionResponse = InferResponseType<UpdateLessonCompl
 export type UpdateLessonCompletionSuccess = Extract<UpdateLessonCompletionResponse, { success: true }>;
 export type UpdateLessonCompletionData = UpdateLessonCompletionSuccess['data'];

+export type GetLessonWatchProgressRequest =
+  (typeof classroomio.course)[':courseId']['lesson'][':lessonId']['watch-progress']['$get'];
+export type GetLessonWatchProgressSuccess = Extract<
+  InferResponseType<GetLessonWatchProgressRequest>,
+  { success: true }
+>;
+export type LessonWatchProgress = GetLessonWatchProgressSuccess['data'];
+
+export type UpdateLessonWatchProgressRequest =
+  (typeof classroomio.course)[':courseId']['lesson'][':lessonId']['watch-progress']['$put'];
+export type UpdateLessonWatchProgressSuccess = Extract<
+  InferResponseType<UpdateLessonWatchProgressRequest>,
+  { success: true }
+>;
+export type LessonWatchProgressUpdate = UpdateLessonWatchProgressSuccess['data'];
+
 // Get lesson history types
 export type GetLessonHistoryRequest =
  (typeof classroomio.course)[':courseId']['lesson'][':lessonId']['history']['$get'];