@lessonkit/react 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -1,20 +1,37 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import React from 'react';
+import React$1 from 'react';
 import * as _lessonkit_core from '@lessonkit/core';
-import { CourseId, TelemetryUser, TrackingClient, LessonkitPlugin, ProgressState, LessonId, TelemetryEventName, TelemetryDataFor, PluginHost, BlockId, AssessmentHandle, AssessmentBaseProps, AssessmentBehaviour, AssessmentAnsweredData, AssessmentCompletedData, CheckId } from '@lessonkit/core';
-export { AssessmentAnsweredData, AssessmentBaseProps, AssessmentBehaviour, AssessmentCompletedData, AssessmentHandle, AssessmentInteractionType, AssessmentScoreInput, AssessmentScoreResult, AssessmentXAPIData, InteractionBlockRegistration, LessonkitPlugin, LessonkitPluginContext, LessonkitPluginKind, PluginHost, PluginRegistry, TelemetryPipelineSink, buildTelemetryEvent, createLessonkitRuntime, createPluginRegistry, createTelemetryPipeline, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin } from '@lessonkit/core';
+import { TelemetryEvent, CourseId, TelemetryUser, TrackingClient, LessonkitPlugin, ProgressState, StoragePort, LessonId, TelemetryEventName, TelemetryDataFor, PluginHost, AssessmentHandle, BlockId, AssessmentBaseProps, AssessmentBehaviour, CompoundHandle, AssessmentAnsweredData, AssessmentCompletedData, CheckId } from '@lessonkit/core';
+export { AssessmentAnsweredData, AssessmentBaseProps, AssessmentBehaviour, AssessmentCompletedData, AssessmentHandle, AssessmentInteractionType, AssessmentScoreInput, AssessmentScoreResult, AssessmentXAPIData, CompoundBaseProps, CompoundHandle, CompoundResumeState, InteractionBlockRegistration, LessonkitPlugin, LessonkitPluginContext, LessonkitPluginKind, PluginHost, PluginRegistry, TelemetryPipelineSink, buildTelemetryEvent, createLessonkitRuntime, createPluginRegistry, createTelemetryPipeline, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin } from '@lessonkit/core';
 import { McqAssessmentDescriptor } from '@lessonkit/lxpack';
 import { XAPITransport, XAPIClient } from '@lessonkit/xapi';
 import { LxpackBridgeMode } from '@lessonkit/lxpack/bridge';
 import { LessonkitThemeV1, ThemePresetName, PartialLessonkitThemeV1 } from '@lessonkit/themes';
 export { ThemePresetName } from '@lessonkit/themes';
 
+type LessonkitObservabilityConfig = {
+    /** Tracking or pipeline sink failure (sync or async). */
+    onTelemetrySinkError?: (err: unknown, ctx: {
+        sinkId?: string;
+    }) => void;
+    /** Current xAPI queue depth after enqueue or flush. */
+    onXapiQueueDepth?: (depth: number) => void;
+    /** Oldest xAPI statement dropped because the queue reached max size. */
+    onXapiQueueCap?: () => void;
+    /** Telemetry batch buffer dropped an event because the cap (1000) was reached. */
+    onTelemetryBufferDrop?: () => void;
+    /** LMS bridge missing for a completion-related telemetry event (`bridge: auto`). */
+    onLxpackBridgeMiss?: (event: TelemetryEvent) => void;
+};
+
 type LessonkitConfig = {
     courseId: CourseId;
     session?: {
         sessionId?: string;
         attemptId?: string;
         user?: TelemetryUser;
+        /** Persist compound navigation and child state in session storage (default true). */
+        persistCompoundState?: boolean;
     };
     tracking?: {
         enabled?: boolean;
@@ -41,17 +58,20 @@ type LessonkitConfig = {
     runtimeVersion?: "v1" | "v2";
     /** Optional custom telemetry pipeline sinks (used alongside tracking/xapi). */
     sinks?: _lessonkit_core.TelemetryPipelineSink[];
+    /** Production hooks for sink failures, xAPI queue depth, and LMS bridge misses. */
+    observability?: LessonkitObservabilityConfig;
 };
 
 type LessonkitProviderProps = {
     config: LessonkitConfig;
-    children: React.ReactNode;
+    children: React$1.ReactNode;
 };
 type LessonkitRuntime = {
     config: LessonkitConfig;
     tracking: TrackingClient;
     xapi: XAPIClient | null;
     progress: ProgressState;
+    storage: StoragePort;
     session: {
         sessionId: string;
         attemptId?: string;
@@ -69,24 +89,28 @@ type LessonkitRuntime = {
 };
 declare function LessonkitProvider(props: LessonkitProviderProps): react_jsx_runtime.JSX.Element;
 
+type QuizProps = McqAssessmentDescriptor;
+declare const Quiz: React$1.ForwardRefExoticComponent<McqAssessmentDescriptor & React$1.RefAttributes<AssessmentHandle>>;
+declare function KnowledgeCheck(props: QuizProps): react_jsx_runtime.JSX.Element;
 /** @internal Reset module warnings between tests. */
 declare function resetQuizWarningsForTests(): void;
+
 type CourseProps = {
     title: string;
     courseId: CourseId;
     config?: Omit<LessonkitConfig, "courseId">;
-    children: React.ReactNode;
+    children: React$1.ReactNode;
 };
 type LessonProps = {
     title: string;
     lessonId: LessonId;
     /** When false, unmount does not emit lesson_completed (for routed multi-pane layouts). Default true. */
     autoCompleteOnUnmount?: boolean;
-    children: React.ReactNode;
+    children: React$1.ReactNode;
 };
 type ScenarioProps = {
     blockId?: BlockId;
-    children: React.ReactNode;
+    children: React$1.ReactNode;
 };
 type ReflectionProps = {
     blockId?: BlockId;
@@ -94,9 +118,8 @@ type ReflectionProps = {
     hint?: string;
     value?: string;
     onChange?: (value: string) => void;
-    children?: React.ReactNode;
+    children?: React$1.ReactNode;
 };
-type QuizProps = McqAssessmentDescriptor;
 type KnowledgeCheckProps = McqAssessmentDescriptor;
 type ProgressTrackerProps = {
     totalLessons?: number;
@@ -105,35 +128,33 @@ declare function Course(props: CourseProps): react_jsx_runtime.JSX.Element;
 declare function Lesson(props: LessonProps): react_jsx_runtime.JSX.Element;
 declare function Scenario(props: ScenarioProps): react_jsx_runtime.JSX.Element;
 declare function Reflection(props: ReflectionProps): react_jsx_runtime.JSX.Element;
-declare function KnowledgeCheck(props: KnowledgeCheckProps): react_jsx_runtime.JSX.Element;
-declare function Quiz(props: QuizProps): react_jsx_runtime.JSX.Element;
 declare function ProgressTracker(props: ProgressTrackerProps): react_jsx_runtime.JSX.Element;
 
 type TrueFalseProps = AssessmentBaseProps & {
     question: string;
     answer: boolean;
 };
-declare const TrueFalse: React.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
+declare const TrueFalse: React$1.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
     checkId: _lessonkit_core.CheckId;
     passingScore?: number;
 } & {
     question: string;
     answer: boolean;
-} & React.RefAttributes<AssessmentHandle>>;
+} & React$1.RefAttributes<AssessmentHandle>>;
 
 type MarkTheWordsProps = AssessmentBaseProps & {
     /** Plain text; words listed in `correctWords` are selectable targets. */
     text: string;
     correctWords: string[];
 };
-declare const MarkTheWords: React.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
+declare const MarkTheWords: React$1.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
     checkId: _lessonkit_core.CheckId;
     passingScore?: number;
 } & {
     /** Plain text; words listed in `correctWords` are selectable targets. */
     text: string;
     correctWords: string[];
-} & React.RefAttributes<AssessmentHandle>>;
+} & React$1.RefAttributes<AssessmentHandle>>;
 
 type FillInBlankSpec = {
     id: string;
@@ -145,7 +166,7 @@ type FillInTheBlanksProps = AssessmentBaseProps & {
     /** Optional explicit blanks (overrides parsing from template). */
     blanks?: FillInBlankSpec[];
 };
-declare const FillInTheBlanks: React.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
+declare const FillInTheBlanks: React$1.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
     checkId: _lessonkit_core.CheckId;
     passingScore?: number;
 } & {
@@ -153,21 +174,21 @@ declare const FillInTheBlanks: React.ForwardRefExoticComponent<_lessonkit_core.A
     template: string;
     /** Optional explicit blanks (overrides parsing from template). */
     blanks?: FillInBlankSpec[];
-} & React.RefAttributes<AssessmentHandle>>;
+} & React$1.RefAttributes<AssessmentHandle>>;
 
 type DragTheWordsProps = AssessmentBaseProps & {
     /** Sentence with `*` around drop zones; `words` are draggable options. */
     template: string;
     words: string[];
 };
-declare const DragTheWords: React.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
+declare const DragTheWords: React$1.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
     checkId: _lessonkit_core.CheckId;
     passingScore?: number;
 } & {
     /** Sentence with `*` around drop zones; `words` are draggable options. */
     template: string;
     words: string[];
-} & React.RefAttributes<AssessmentHandle>>;
+} & React$1.RefAttributes<AssessmentHandle>>;
 
 type DragItem = {
     id: string;
@@ -182,20 +203,185 @@ type DragAndDropProps = AssessmentBaseProps & {
     items: DragItem[];
     targets: DropTarget[];
 };
-declare const DragAndDrop: React.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
+declare const DragAndDrop: React$1.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
     checkId: _lessonkit_core.CheckId;
     passingScore?: number;
 } & {
     items: DragItem[];
     targets: DropTarget[];
-} & React.RefAttributes<AssessmentHandle>>;
+} & React$1.RefAttributes<AssessmentHandle>>;
 
 type AssessmentSequenceProps = AssessmentBehaviour & {
-    children: React.ReactNode;
+    children: React$1.ReactNode;
+    /** Show one child assessment at a time (Question Set). */
+    sequential?: boolean;
+    blockId?: BlockId;
+};
+declare const AssessmentSequence: React$1.ForwardRefExoticComponent<AssessmentBehaviour & {
+    children: React$1.ReactNode;
     /** Show one child assessment at a time (Question Set). */
     sequential?: boolean;
+    blockId?: BlockId;
+} & React$1.RefAttributes<CompoundHandle>>;
+
+type TextProps = {
+    blockId?: BlockId;
+    children: React$1.ReactNode;
+};
+declare function Text(props: TextProps): react_jsx_runtime.JSX.Element;
+
+type HeadingProps = {
+    blockId?: BlockId;
+    level: 1 | 2 | 3;
+    children: React.ReactNode;
+};
+declare function Heading(props: HeadingProps): react_jsx_runtime.JSX.Element;
+
+type ImageProps = {
+    blockId?: BlockId;
+    src: string;
+    alt: string;
+};
+declare function Image(props: ImageProps): react_jsx_runtime.JSX.Element;
+
+type PageProps = {
+    blockId: BlockId;
+    title?: string;
+    /** When true, page is used as a book chapter but hidden until navigated (InteractiveBook). */
+    hidden?: boolean;
+    /** Index within a compound parent (set by InteractiveBook). */
+    pageIndex?: number;
+    /** Compound parent type for telemetry (e.g. InteractiveBook). */
+    parentType?: string;
+    children: React$1.ReactNode;
+};
+declare function Page(props: PageProps): react_jsx_runtime.JSX.Element;
+
+type InteractiveBookProps = {
+    blockId: BlockId;
+    title: string;
+    showBookScore?: boolean;
+    children: React$1.ReactElement<PageProps> | React$1.ReactElement<PageProps>[];
+};
+declare const InteractiveBook: React$1.ForwardRefExoticComponent<InteractiveBookProps & React$1.RefAttributes<CompoundHandle>>;
+
+type SlideProps = {
+    blockId: BlockId;
+    title?: string;
+    /** When true, slide is used in a deck but hidden until navigated (SlideDeck). */
+    hidden?: boolean;
+    /** Index within a compound parent (set by SlideDeck). */
+    slideIndex?: number;
+    /** Compound parent type for telemetry (e.g. SlideDeck). */
+    parentType?: string;
+    children: React$1.ReactNode;
+};
+declare function Slide(props: SlideProps): react_jsx_runtime.JSX.Element;
+
+type SlideDeckProps = {
+    blockId: BlockId;
+    title: string;
+    showDeckScore?: boolean;
+    children: React$1.ReactElement<SlideProps> | React$1.ReactElement<SlideProps>[];
+};
+declare const SlideDeck: React$1.ForwardRefExoticComponent<SlideDeckProps & React$1.RefAttributes<CompoundHandle>>;
+
+type AccordionSection = {
+    id: string;
+    title: string;
+    content: React$1.ReactNode;
+};
+type AccordionProps = {
+    blockId: BlockId;
+    sections: AccordionSection[];
+};
+declare function Accordion(props: AccordionProps): react_jsx_runtime.JSX.Element;
+
+type DialogCard = {
+    front: string;
+    back: string;
+};
+type DialogCardsProps = {
+    blockId: BlockId;
+    cards: DialogCard[];
+};
+declare function DialogCards(props: DialogCardsProps): react_jsx_runtime.JSX.Element | null;
+
+type Flashcard = {
+    front: string;
+    back: string;
+};
+type FlashcardsProps = {
+    blockId: BlockId;
+    cards: Flashcard[];
+    /** Optional self-score mode (not LMS-scored). */
+    selfScore?: boolean;
+};
+declare function Flashcards(props: FlashcardsProps): react_jsx_runtime.JSX.Element | null;
+
+type HotspotSpec = {
+    id: string;
+    label: string;
+    x: number;
+    y: number;
+    content: React$1.ReactNode;
+};
+type ImageHotspotsProps = {
+    blockId: BlockId;
+    src: string;
+    alt: string;
+    hotspots: HotspotSpec[];
 };
-declare function AssessmentSequence(props: AssessmentSequenceProps): react_jsx_runtime.JSX.Element;
+declare function ImageHotspots(props: ImageHotspotsProps): react_jsx_runtime.JSX.Element;
+
+type ImageSlide = {
+    src: string;
+    alt: string;
+    caption?: string;
+};
+type ImageSliderProps = {
+    blockId: BlockId;
+    slides: ImageSlide[];
+};
+declare function ImageSlider(props: ImageSliderProps): react_jsx_runtime.JSX.Element | null;
+
+type HotspotTarget = {
+    id: string;
+    label: string;
+    x: number;
+    y: number;
+};
+type FindHotspotProps = AssessmentBaseProps & {
+    src: string;
+    alt: string;
+    targets: HotspotTarget[];
+    correctTargetId: string;
+};
+declare const FindHotspot: React$1.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
+    checkId: _lessonkit_core.CheckId;
+    passingScore?: number;
+} & {
+    src: string;
+    alt: string;
+    targets: HotspotTarget[];
+    correctTargetId: string;
+} & React$1.RefAttributes<AssessmentHandle>>;
+
+type FindMultipleHotspotsProps = AssessmentBaseProps & {
+    src: string;
+    alt: string;
+    targets: HotspotTarget[];
+    correctTargetIds: string[];
+};
+declare const FindMultipleHotspots: React$1.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
+    checkId: _lessonkit_core.CheckId;
+    passingScore?: number;
+} & {
+    src: string;
+    alt: string;
+    targets: HotspotTarget[];
+    correctTargetIds: string[];
+} & React$1.RefAttributes<AssessmentHandle>>;
 
 declare function useAssessmentState(enclosingLessonId?: LessonId): {
     answer: (data: AssessmentAnsweredData) => void;
@@ -236,7 +422,7 @@ declare function resetAssessmentWarningsForTests(): void;
 type ThemeMode = "light" | "dark" | "system";
 type ThemeResolvedMode = "light" | "dark";
 type ThemeProviderProps = {
-    children: React.ReactNode;
+    children: React$1.ReactNode;
     /** Partial theme merged on top of the resolved preset (last writer wins). */
     theme?: PartialLessonkitThemeV1;
     preset?: ThemePresetName;
@@ -255,6 +441,7 @@ declare function useTheme(): ThemeContextValue;
 
 declare const blockCatalogVersion: 1;
 declare const blockCatalogV2Version: 2;
+declare const blockCatalogV3Version: 3;
 type BlockPropSpec = {
     name: string;
     type: string;
@@ -291,9 +478,13 @@ type BlockCatalogEntryBase = {
 type BlockCatalogEntry = BlockCatalogEntryBase;
 type BlockCatalogEntryV2 = BlockCatalogEntryBase & {
     assessmentContract?: true;
+    compoundContract?: true;
     h5pMachineName?: string;
     h5pAlias?: string;
+    allowedChildTypes?: readonly string[];
+    maxNestingDepth?: number;
 };
+type BlockCatalogEntryV3 = BlockCatalogEntryV2;
 declare const BLOCK_CATALOG: ({
     type: string;
     category: "container";
@@ -502,10 +693,11 @@ declare const BLOCK_CATALOG: ({
     aliases?: undefined;
 })[];
 declare const BLOCK_CATALOG_V2: BlockCatalogEntryV2[];
+declare const BLOCK_CATALOG_V3: BlockCatalogEntryV3[];
 type BuildBlockCatalogOptions = {
-    version?: 1 | 2;
+    version?: 1 | 2 | 3;
 };
-declare function buildBlockCatalog(opts?: BuildBlockCatalogOptions): BlockCatalogEntry[] | BlockCatalogEntryV2[];
-declare function getBlockCatalogEntry(type: string, opts?: BuildBlockCatalogOptions): BlockCatalogEntry | BlockCatalogEntryV2 | undefined;
+declare function buildBlockCatalog(opts?: BuildBlockCatalogOptions): BlockCatalogEntry[] | BlockCatalogEntryV2[] | BlockCatalogEntryV3[];
+declare function getBlockCatalogEntry(type: string, opts?: BuildBlockCatalogOptions): BlockCatalogEntry | BlockCatalogEntryV2 | BlockCatalogEntryV3 | undefined;
 
-export { AssessmentSequence, type AssessmentSequenceProps, BLOCK_CATALOG, BLOCK_CATALOG_V2, type BlockCatalogEntry, type BlockCatalogEntryV2, type BlockPropSpec, Course, type CourseProps, DragAndDrop, type DragAndDropProps, type DragItem, DragTheWords, type DragTheWordsProps, type DropTarget, type FillInBlankSpec, FillInTheBlanks, type FillInTheBlanksProps, KnowledgeCheck, type KnowledgeCheckProps, Lesson, type LessonProps, type LessonkitConfig, LessonkitProvider, type LessonkitProviderProps, type LessonkitRuntime, MarkTheWords, type MarkTheWordsProps, ProgressTracker, type ProgressTrackerProps, Quiz, type QuizProps, Reflection, type ReflectionProps, Scenario, type ScenarioProps, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeResolvedMode, TrueFalse, type TrueFalseProps, blockCatalogV2Version, blockCatalogVersion, buildBlockCatalog, getBlockCatalogEntry, resetAssessmentWarningsForTests, resetQuizWarningsForTests, useAssessmentState, useCompletion, useLessonkit, useProgress, useQuizState, useTheme, useTracking };
+export { Accordion, type AccordionProps, type AccordionSection, AssessmentSequence, type AssessmentSequenceProps, BLOCK_CATALOG, BLOCK_CATALOG_V2, BLOCK_CATALOG_V3, type BlockCatalogEntry, type BlockCatalogEntryV2, type BlockCatalogEntryV3, type BlockPropSpec, Course, type CourseProps, type DialogCard, DialogCards, type DialogCardsProps, DragAndDrop, type DragAndDropProps, type DragItem, DragTheWords, type DragTheWordsProps, type DropTarget, type FillInBlankSpec, FillInTheBlanks, type FillInTheBlanksProps, FindHotspot, type FindHotspotProps, FindMultipleHotspots, type FindMultipleHotspotsProps, type Flashcard, Flashcards, type FlashcardsProps, Heading, type HeadingProps, type HotspotSpec, type HotspotTarget, Image, ImageHotspots, type ImageHotspotsProps, type ImageProps, type ImageSlide, ImageSlider, type ImageSliderProps, InteractiveBook, type InteractiveBookProps, KnowledgeCheck, type KnowledgeCheckProps, Lesson, type LessonProps, type LessonkitConfig, type LessonkitObservabilityConfig, LessonkitProvider, type LessonkitProviderProps, type LessonkitRuntime, MarkTheWords, type MarkTheWordsProps, Page, type PageProps, ProgressTracker, type ProgressTrackerProps, Quiz, type QuizProps, Reflection, type ReflectionProps, Scenario, type ScenarioProps, Slide, SlideDeck, type SlideDeckProps, type SlideProps, Text, type TextProps, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeResolvedMode, TrueFalse, type TrueFalseProps, blockCatalogV2Version, blockCatalogV3Version, blockCatalogVersion, buildBlockCatalog, getBlockCatalogEntry, resetAssessmentWarningsForTests, resetQuizWarningsForTests, useAssessmentState, useCompletion, useLessonkit, useProgress, useQuizState, useTheme, useTracking };