@lessonkit/react 1.0.2 → 1.2.0

package/dist/index.d.ts

@@ -1,20 +1,35 @@
 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, CheckId } from '@lessonkit/core';
-export { AssessmentScoreInput, AssessmentScoreResult, InteractionBlockRegistration, LessonkitPlugin, LessonkitPluginContext, LessonkitPluginKind, PluginHost, PluginRegistry, TelemetryPipelineSink, buildTelemetryEvent, createLessonkitRuntime, createPluginRegistry, createTelemetryPipeline, defineAssessmentPlugin, defineLifecyclePlugin, defineTelemetryPlugin } from '@lessonkit/core';
-import { AssessmentDescriptor } from '@lessonkit/lxpack';
+import { TelemetryEvent, CourseId, TelemetryUser, TrackingClient, LessonkitPlugin, ProgressState, 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;
+    /** 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,11 +56,13 @@ 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;
@@ -69,24 +86,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,10 +115,9 @@ type ReflectionProps = {
     hint?: string;
     value?: string;
     onChange?: (value: string) => void;
-    children?: React.ReactNode;
+    children?: React$1.ReactNode;
 };
-type QuizProps = AssessmentDescriptor;
-type KnowledgeCheckProps = AssessmentDescriptor;
+type KnowledgeCheckProps = McqAssessmentDescriptor;
 type ProgressTrackerProps = {
     totalLessons?: number;
 };
@@ -105,10 +125,245 @@ 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$1.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
+    checkId: _lessonkit_core.CheckId;
+    passingScore?: number;
+} & {
+    question: string;
+    answer: boolean;
+} & React$1.RefAttributes<AssessmentHandle>>;
+
+type MarkTheWordsProps = AssessmentBaseProps & {
+    /** Plain text; words listed in `correctWords` are selectable targets. */
+    text: string;
+    correctWords: string[];
+};
+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$1.RefAttributes<AssessmentHandle>>;
+
+type FillInBlankSpec = {
+    id: string;
+    answer: string;
+};
+type FillInTheBlanksProps = AssessmentBaseProps & {
+    /** Text with `*` wrapping each blank answer, e.g. "The *capital* of France is *Paris*." */
+    template: string;
+    /** Optional explicit blanks (overrides parsing from template). */
+    blanks?: FillInBlankSpec[];
+};
+declare const FillInTheBlanks: React$1.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
+    checkId: _lessonkit_core.CheckId;
+    passingScore?: number;
+} & {
+    /** Text with `*` wrapping each blank answer, e.g. "The *capital* of France is *Paris*." */
+    template: string;
+    /** Optional explicit blanks (overrides parsing from template). */
+    blanks?: FillInBlankSpec[];
+} & React$1.RefAttributes<AssessmentHandle>>;
+
+type DragTheWordsProps = AssessmentBaseProps & {
+    /** Sentence with `*` around drop zones; `words` are draggable options. */
+    template: string;
+    words: string[];
+};
+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$1.RefAttributes<AssessmentHandle>>;
+
+type DragItem = {
+    id: string;
+    label: string;
+};
+type DropTarget = {
+    id: string;
+    label: string;
+    accepts: string;
+};
+type DragAndDropProps = AssessmentBaseProps & {
+    items: DragItem[];
+    targets: DropTarget[];
+};
+declare const DragAndDrop: React$1.ForwardRefExoticComponent<_lessonkit_core.AssessmentBehaviour & {
+    checkId: _lessonkit_core.CheckId;
+    passingScore?: number;
+} & {
+    items: DragItem[];
+    targets: DropTarget[];
+} & React$1.RefAttributes<AssessmentHandle>>;
+
+type AssessmentSequenceProps = AssessmentBehaviour & {
+    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 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 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;
+    complete: (data: AssessmentCompletedData) => void;
+};
+
 declare function useLessonkit(): LessonkitRuntime;
 declare function useProgress(): _lessonkit_core.ProgressState;
 declare function useTracking(): {
@@ -122,6 +377,7 @@ declare function useCompletion(): {
     }) => void;
     completeCourse: () => void;
 };
+
 declare function useQuizState(enclosingLessonId?: LessonId): {
     answer: (opts: {
         checkId: CheckId;
@@ -137,10 +393,12 @@ declare function useQuizState(enclosingLessonId?: LessonId): {
     }) => void;
 };
 
+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;
@@ -158,13 +416,15 @@ declare function ThemeProvider(props: ThemeProviderProps): react_jsx_runtime.JSX
 declare function useTheme(): ThemeContextValue;
 
 declare const blockCatalogVersion: 1;
+declare const blockCatalogV2Version: 2;
+declare const blockCatalogV3Version: 3;
 type BlockPropSpec = {
     name: string;
     type: string;
     required: boolean;
     description: string;
 };
-type BlockCatalogEntry = {
+type BlockCatalogEntryBase = {
     type: string;
     aliases?: string[];
     category: "container" | "content" | "assessment" | "chrome";
@@ -191,6 +451,16 @@ type BlockCatalogEntry = {
         manualTracking?: string;
     };
 };
+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";
@@ -398,7 +668,12 @@ declare const BLOCK_CATALOG: ({
     optionalIds?: undefined;
     aliases?: undefined;
 })[];
-declare function buildBlockCatalog(): BlockCatalogEntry[];
-declare function getBlockCatalogEntry(type: string): BlockCatalogEntry | undefined;
+declare const BLOCK_CATALOG_V2: BlockCatalogEntryV2[];
+declare const BLOCK_CATALOG_V3: BlockCatalogEntryV3[];
+type BuildBlockCatalogOptions = {
+    version?: 1 | 2 | 3;
+};
+declare function buildBlockCatalog(opts?: BuildBlockCatalogOptions): BlockCatalogEntry[] | BlockCatalogEntryV2[] | BlockCatalogEntryV3[];
+declare function getBlockCatalogEntry(type: string, opts?: BuildBlockCatalogOptions): BlockCatalogEntry | BlockCatalogEntryV2 | BlockCatalogEntryV3 | undefined;
 
-export { BLOCK_CATALOG, type BlockCatalogEntry, type BlockPropSpec, Course, type CourseProps, KnowledgeCheck, type KnowledgeCheckProps, Lesson, type LessonProps, type LessonkitConfig, LessonkitProvider, type LessonkitProviderProps, type LessonkitRuntime, ProgressTracker, type ProgressTrackerProps, Quiz, type QuizProps, Reflection, type ReflectionProps, Scenario, type ScenarioProps, type ThemeContextValue, type ThemeMode, ThemeProvider, type ThemeProviderProps, type ThemeResolvedMode, blockCatalogVersion, buildBlockCatalog, getBlockCatalogEntry, resetQuizWarningsForTests, 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, 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 };