@intellectif/lk-react 23.1.0 → 23.1.2

package/dist/components/ActivitySequence.cjs

@@ -1,31 +1,4 @@
 'use client';
-'use strict';
-
-var chunkKFLIDTDU_cjs = require('../chunk-KFLIDTDU.cjs');
-require('../chunk-RPWUDXG5.cjs');
-require('../chunk-MKXEM2C5.cjs');
-require('../chunk-YY4PFR3Z.cjs');
-require('../chunk-DS6HN3YR.cjs');
-require('../chunk-7ALBSPYR.cjs');
-require('../chunk-NAK55BYU.cjs');
-require('../chunk-KHKH5LCT.cjs');
-require('../chunk-TP5UMRAU.cjs');
-require('../chunk-LBEKRN6Y.cjs');
-require('../chunk-UDCQTOVU.cjs');
-require('../chunk-OD65OZIW.cjs');
-require('../chunk-2PNSVBLQ.cjs');
-require('../chunk-J3C72RPK.cjs');
-require('../chunk-LPUWXIPR.cjs');
-require('../chunk-NDBMKGQ5.cjs');
-require('../chunk-XOR4MPEN.cjs');
-require('../chunk-BIGGXHAW.cjs');
-require('../chunk-TUVENMXB.cjs');
-
-
-
-Object.defineProperty(exports, "ActivitySequence", {
-  enumerable: true,
-  get: function () { return chunkKFLIDTDU_cjs.ActivitySequence; }
-});
-//# sourceMappingURL=ActivitySequence.cjs.map
-//# sourceMappingURL=ActivitySequence.cjs.map
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_ActivitySequence = require("../ActivitySequence-CmoSyDnp.cjs");
+exports.ActivitySequence = require_ActivitySequence.ActivitySequence;

package/dist/components/ActivitySequence.d.cts

@@ -1,432 +1,2 @@
-import { InteractionKind, SequenceEntry, ActivityResult, LearnerResponse, InteractionEvent, SpeechAssessment, DeliveryPolicy, ItemScoringPolicy, ItemOutcome, ThemeTokens } from '@intellectif/lk-core';
-import { ComponentType } from 'react';
-import { LearnerAi } from '../ai/LkAiProvider.cjs';
-import { A as ActivityProps, i as SequenceRecordingSlot, g as RenderableActivity, e as RenderMode, S as SequenceMediaBudget, h as SequenceRecordingBinding, a as LkStringsOverride, H as HtmlSanitizer } from '../types-CJgZWtl4.cjs';
-import { a as WrittenResponseSubmission } from '../WrittenResponse-BpL9p2Hn.cjs';
-import '../machine-CuwKqWXC.cjs';
-
-/**
- * What one finished slot in a sequence produced. Two kinds, because two kinds
- * of activity exist: those the SDK scores at submit time, and those a grader
- * scores later. Collapsing them would mean inventing a score for ungraded
- * work — the exact defect the deferred outcome exists to prevent.
- *
- * **A read-aloud hand-in adds no arm here, deliberately.** The obvious home for
- * a handed-in take is `submitted`, and it is the wrong one: that arm's payload
- * is typed `WrittenResponseSubmission`, this union is published from both the
- * barrel and the `components/ActivitySequence` subpath, and a consumer narrows
- * on `kind === 'submitted'` and reads `.text`. Widening the payload to a union
- * would break every one of those reads — a breaking change to a published
- * discriminated union, bought for a type that `responded` already describes: a
- * read-aloud hand-in IS a raw `LearnerResponse` with no grade, which is exactly
- * what `responded` carries.
- *
- * What a read-aloud does add is `unsubmitted`, for the one thing no existing
- * arm can say honestly: a take that never reached storage. Any response would
- * be a lie about it — a `recording` of `null` is the blank a learner chooses,
- * and grades as 0.
- */
-type SequenceItemOutcome = {
-    kind: 'scored';
-    /** Presented position. */
-    index: number;
-    /** Slot identity from `flattenSequence` — stable under shuffling; the `slotId` to score with. */
-    slotId: string;
-    activityId: string;
-    result: ActivityResult;
-    /**
-     * The answer this score grades, for a slot whose grade arrives after its
-     * answer was handed in and whose learner may hand in another: a
-     * `practice` read-aloud, whose `response.recording` names the take the
-     * score belongs to. Absent for every other slot, whose score and answer
-     * arrive together.
-     */
-    response?: LearnerResponse;
-} | {
-    kind: 'submitted';
-    index: number;
-    slotId: string;
-    activityId: string;
-    /** Ungraded submission; the grade arrives asynchronously. */
-    submission: WrittenResponseSubmission;
-} | {
-    kind: 'restored';
-    index: number;
-    slotId: string;
-    activityId: string;
-    /**
-     * The answer as restored, when one was. A slot can be submitted with no
-     * stored response (a blank the learner committed), so this is optional —
-     * inventing one would be worse than admitting it is absent.
-     */
-    response?: LearnerResponse;
-} | {
-    kind: 'responded';
-    index: number;
-    slotId: string;
-    activityId: string;
-    /**
-     * The raw answer, with no grade of any kind. This is what an `exam` slot
-     * produces: the client is forbidden to score, so a response is all there
-     * is until the server grades it.
-     *
-     * A read-aloud `recording` of `null` here is always a blank the learner
-     * chose to hand in, never a take that failed to upload — that is
-     * `unsubmitted`.
-     */
-    response: LearnerResponse;
-} | {
-    /**
-     * A question the learner tried to answer and could not hand in, and then
-     * left: a `practice` read-aloud whose take never reached your storage. It
-     * carries no response, because there is none.
-     *
-     * Deliberately not `responded` with a `recording` of `null`: that is the
-     * blank a learner chooses, and a grader marks it 0 with every word
-     * omitted — which would turn a storage outage into a zero. Grade nothing
-     * for this slot; the learner can still return to it, and a take stored
-     * then reaches you through `onSubmit`.
-     */
-    kind: 'unsubmitted';
-    index: number;
-    slotId: string;
-    activityId: string;
-};
-/**
- * Where a question sits in the set, and the calls that tell the pager what the
- * learner did with it — handed to a `renderers` override as its `question`
- * prop, beside the shared {@link ActivityProps}.
- *
- * The SDK's own components make the same calls, so a question a host draws
- * counts exactly as one the SDK draws: in `onFinished`, in whether the set is
- * complete, and in what a resumed attempt reopens. Every call here keeps ONE
- * identity for the life of the set, so it is safe in an effect's dependencies,
- * and does nothing once the set has changed or the pager has gone.
- */
-interface SequenceQuestion {
-    /**
-     * The identity to store this question's answer against — the same object
-     * `onSubmit` and `onActivityComplete` are handed, for the life of the set.
-     * `slotId`, never `index`: the position moves under shuffling.
-     */
-    slot: SequenceRecordingSlot;
-    /**
-     * `true` while this is the question on screen. `false` from the moment the
-     * learner pages away, and `true` again when they come back.
-     *
-     * WHEN IT TURNS `false`, STOP THE MICROPHONE, ANY TIMER AND ANY SPEECH. The
-     * pager pauses the `<audio>` and `<video>` elements inside the question and
-     * stops the recorders the SDK started, but it cannot reach a recorder it did
-     * not create.
-     */
-    active: boolean;
-    /**
-     * An element inside this question's own pane, for popovers, tooltips and
-     * dialogs. Portal into it rather than into `document.body`: a pane the
-     * learner has paged away from is hidden, and anything portalled out of it
-     * stays on screen over the next question — and in fullscreen, only the
-     * subtree being painted is visible at all.
-     *
-     * It is the same element for as long as the set is on screen, and is `null`
-     * only before the first commit.
-     */
-    portalContainer: HTMLElement | null;
-    /**
-     * The learner withdrew their answer — a "Try again". The question counts as
-     * unanswered again and its outcome is forgotten, so the set is not complete
-     * until it is answered again. Calls no host callback: the host already knows.
-     */
-    clear(): void;
-    /**
-     * Work is on its way for this question — an upload, an assessment, a save.
-     * While any question is pending, the set is not reported: `onFinished` and
-     * `onComplete` wait for it. Paging does not wait.
-     *
-     * Call `setPending(false)` however the work ends, a failure included.
-     */
-    setPending(pending: boolean): void;
-    /** Forwards to `onInteraction`, with this question's `activityId` and the time filled in. */
-    emit(type: InteractionKind, payload?: Record<string, unknown>): void;
-}
-/**
- * A component that can render one activity inside a sequence. Register one per
- * activity `type` to put a consumer-defined type on screen — the React half of
- * the activity-type registry, matching `registerActivityType` in lk-core.
- *
- * It receives the shared {@link ActivityProps} and one prop beyond them:
- * `question`, the pager's half of the contract ({@link SequenceQuestion}). A
- * renderer written as `ComponentType<ActivityProps>` still fits and simply
- * ignores it.
- */
-type ActivityRenderer = ComponentType<ActivityProps & {
-    question?: SequenceQuestion;
-}>;
-interface ActivitySequenceProps {
-    /**
-     * The ordered set of entries to present, one question at a time: loose
-     * activities, and item groups — a shared passage, recording or image with
-     * the questions that refer to it. A group's stimulus stays on screen
-     * alongside each of its questions.
-     *
-     * Accepts `redact()` projections. For data straight off a server, pass it
-     * through `asRenderableSequence()` — see that helper for why a cast is
-     * unavoidable there — and set `renderMode="exam"`.
-     */
-    activities: readonly SequenceEntry<RenderableActivity>[];
-    /**
-     * Renderers for activity types beyond the built-ins, keyed by `data.type`.
-     * A key matching a built-in overrides it, so a consumer can replace the
-     * bundled renderer without forking the sequencer.
-     *
-     * A registered renderer is an {@link ActivityRenderer}: it receives the
-     * shared prop contract, plus `question` — the pager's half of the contract
-     * ({@link SequenceQuestion}), which tells it when its question is on screen,
-     * holds the set while its work is in flight, and gives it somewhere to
-     * portal a popover. `shuffleSeed`, `recordingBinding`, `assessment` and
-     * `workletUrl` are outside both and reach no override: a replacement for
-     * `read-aloud` has to be given its own binding by whoever wrote it.
-     */
-    renderers?: Readonly<Record<string, ActivityRenderer>>;
-    /**
-     * Called whenever an individual activity is scored at submit time — the
-     * incremental persist hook.
-     *
-     * `slotId` is the identity to store the result against, NOT `index`.
-     * `index` is where the question was PRESENTED, which is not stable: it moves
-     * under shuffling, and it already differs from the slot identity whenever a
-     * group is present (the second entry of a sequence is presented at index 1
-     * but is slot `"1.0"` if it is a group's first question). `composeAssessmentScore`
-     * scores by `slotId`, so persisting `index` cannot be reconciled with it.
-     */
-    onActivityComplete?: (result: ActivityResult, index: number, slotId: string) => void;
-    /**
-     * Called on every submit with the learner's raw response and the identity of
-     * the slot that produced it — before any grading, in every render mode.
-     *
-     * **This is the only response channel an `exam` sequence has.** In `exam`
-     * mode the components never grade, so `onActivityComplete` cannot fire and
-     * `onComplete` never will; without this prop nothing a learner submitted
-     * would reach the consumer at all. Persist `response` against `slotId`.
-     */
-    onSubmit?: (response: LearnerResponse, slot: {
-        slotId: string;
-        index: number;
-        activityId: string;
-    }) => void;
-    /**
-     * Called once every activity has been completed, with the scored results.
-     *
-     * Fires only when EVERY item produced a score. A set containing a
-     * deferred-graded activity (a written response) can never satisfy that, so
-     * use `onFinished` for mixed sets — it is the general completion signal and
-     * reports both kinds of outcome. It also carries `slotId` per item, which
-     * this callback's bare array cannot.
-     *
-     * It fires straight after `onFinished`, with the same results, or never: a
-     * set `onFinished` reported with an ungraded slot is not reported here later,
-     * when a re-recorded take is graded.
-     */
-    onComplete?: (results: ActivityResult[]) => void;
-    /**
-     * Called once every activity has been completed, whether it was scored at
-     * submit time or submitted for later grading. Use this for any set that
-     * mixes graded and deferred-graded activities.
-     *
-     * **Once per set**, and that matters for a `practice` read-aloud, whose grade
-     * arrives after the submit that completed the slot. When the last slot is
-     * filled while a read-aloud's take is still being stored or assessed, this
-     * waits for it and reports the set then — with the grade in place, or with
-     * the slot's raw `responded` outcome when the take came back with no grade.
-     * A take that never settles is a question still being answered, so the set
-     * is not reported while it runs.
-     *
-     * **A failure the learner can still retry is in flight too.** While a take
-     * that failed to upload, or whose assessment failed, is offered "Try again"
-     * on the question the learner is looking at, the set is not reported: the
-     * retry may yet store and grade it. It completes once the learner moves to
-     * another question — as the last take the slot stored, or as `unsubmitted`
-     * when it never stored one, which is never a blank.
-     *
-     * **A score and a response always describe the same take.** A read-aloud
-     * recorded again replaces the earlier take's grade with the new take's
-     * `responded`, and a result that arrives for a take the learner has since
-     * replaced, or for a paper no longer on screen, is not recorded at all.
-     *
-     * `onComplete` fires in the same report or not at all, so the two never
-     * describe one set differently. What arrives after the set was reported is
-     * not reported here again, because a consumer who persists on this callback
-     * must not write one attempt twice: a later take reaches you through
-     * `onSubmit`, and its grade through `onActivityComplete`, the per-item persist
-     * hook keyed by `slotId` — which only ever grades the answer `onSubmit` last
-     * reported for that slot.
-     */
-    onFinished?: (items: SequenceItemOutcome[]) => void;
-    /** Forwarded to each activity. */
-    onInteraction?: (event: InteractionEvent) => void;
-    /** Forwarded to each activity. `exam` and `review` disable local scoring. */
-    renderMode?: RenderMode;
-    /**
-     * Binds every budgeted recording in this sequence to a play ledger the
-     * consumer persists.
-     *
-     * The SDK refuses a play; it does not remember one. `plays` seeds the counts
-     * at mount (pass `restoreMediaPlayLedger(plan, stored).entries`), and
-     * `onPlayConsumed` is how a play becomes durable — see
-     * {@link SequenceMediaBudget}.
-     */
-    mediaBudget?: SequenceMediaBudget;
-    /**
-     * Where every read-aloud take in this sequence is stored, and how a
-     * judgement comes back. Required by any `read-aloud` slot outside `review`:
-     * the component refuses to render a recorder whose take is stored nowhere.
-     *
-     * Named `recordingBinding` rather than `recording` because both
-     * `ReadAloudData.recording` (the bounds an item declares) and
-     * `ReadAloudLearnerResponse.recording` (the take a learner handed in) already
-     * exist — the plain name would read as one of those. Same name at both
-     * levels, different types, as `mediaBudget` has.
-     */
-    recordingBinding?: SequenceRecordingBinding;
-    /**
-     * Speech assessments keyed by `slotId`, forwarded to the matching read-aloud
-     * slot so `review` can show the per-word marks behind a stored grade.
-     *
-     * Read LIVE, like `outcomes` and unlike `responses`: an assessment is fetched
-     * beside the attempt it explains and lands after the first paint, and a
-     * mount-only read would show the grade with no marks under it for ever.
-     */
-    assessments?: Readonly<Record<string, SpeechAssessment>>;
-    /**
-     * The URL of a self-hosted copy of `CAPTURE_PROCESSOR_SOURCE`, forwarded to
-     * every read-aloud slot's recorder, for a Content-Security-Policy whose
-     * `script-src` does not allow `blob:`. See `ReadAloudProps.workletUrl`. Like
-     * `recordingBinding`, it does not reach a `renderers` override.
-     */
-    workletUrl?: string;
-    /** Overrides the SDK's chrome text for this sequence. See {@link LkIntlProvider}. */
-    strings?: LkStringsOverride;
-    /**
-     * The host's AI ports, for every question this renders: explanations after
-     * grading, hints before submit. The same as `LkAiProvider`, for this one
-     * sequence, and a `renderers` override receives them as its own `ai` prop —
-     * except in `exam`, where nothing AI appears and no question is given them.
-     * See {@link LearnerAi}.
-     */
-    ai?: LearnerAi;
-    /**
-     * What the school running this paper lets a learner see — feedback,
-     * solutions, hints, AI help — for every question in it. Each setting only
-     * takes away from what `renderMode` shows; an absent policy takes nothing.
-     *
-     * It holds in every question however it is drawn: the SDK's own components
-     * and a `renderers` override are handed it as `delivery`, and a question
-     * that ignores what it was handed still cannot show AI help the paper
-     * forbids. Record the same policy in the attempt with
-     * `planAttempt(entries, { delivery })`. See `DeliveryPolicy` in lk-core.
-     */
-    delivery?: DeliveryPolicy | null;
-    /**
-     * How every question in the paper is scored when a learner can try again or
-     * ask for hints: how many tries each gives, which one counts, and what tries
-     * and hints cost. Applies in `practice`, where the questions grade; absent,
-     * each question is one try and costs nothing, as before.
-     *
-     * It holds in every question: the paper's policy wins over one a question
-     * was handed. The set is not reported while the question on screen offers
-     * another try, nor while any question is being tried again — the next try
-     * may change its grade — and once the set is reported, every question's
-     * tries close. A later try replaces a question's
-     * outcome until then, so `onActivityComplete` can fire more than once for a
-     * slot: keep the last. Record the same policy with
-     * `planAttempt(entries, { scoring })`. See `ItemScoringPolicy` in lk-core.
-     *
-     * A policy `validateItemScoringPolicy` refuses throws at render.
-     */
-    scoring?: ItemScoringPolicy | null;
-    /**
-     * `entries` shuffles the top-level entries; a group moves as one block, and
-     * the order INSIDE a group follows the group's own `shuffle` setting.
-     * Default `none`: authored order.
-     */
-    shuffle?: 'none' | 'entries';
-    /**
-     * Seed for every shuffle in this sequence (`shuffle: 'entries'` and any
-     * group with `shuffle: 'within-group'`). Supply the attempt id, so the
-     * server's `flattenSequence(entries, { seed })` derives the same order this
-     * pager shows.
-     *
-     * **Required whenever this sequence shuffles** — `shuffle: 'entries'`, or any
-     * group with `shuffle: 'within-group'` — in `exam` or `review` mode; omitting
-     * it then throws. An order nobody can reproduce cannot be reconciled with a
-     * recorded attempt, and failing at render is the only way that mistake
-     * surfaces before a learner sits the paper. A sequence that does not shuffle
-     * needs no seed in any mode.
-     *
-     * The guard covers an activity's own `data.shuffle` too, a group's items
-     * included: `<MultipleChoice>` would otherwise fall back to a per-mount seed,
-     * in every mode.
-     *
-     * In `practice` mode it stays optional: a random per-mount seed is used,
-     * stable within the mount and deliberately not reproducible. That fallback is
-     * also not SSR-safe (server and client would invent different orders and
-     * hydration would mismatch), so supply a seed for any server-rendered
-     * sequence regardless of mode.
-     */
-    shuffleSeed?: string;
-    /**
-     * Where to open. Defaults to the first question; pass a stored
-     * `AttemptState.index` to reopen an interrupted attempt where it was left.
-     * Read at mount only, like any `default*` prop.
-     */
-    defaultIndex?: number;
-    /**
-     * Fires whenever the learner moves. Persist it and the next resume reopens
-     * on the right question — without it, the pager's position is the one piece
-     * of an attempt a consumer cannot recover.
-     */
-    onIndexChange?: (index: number) => void;
-    /**
-     * Answers to restore, keyed by `slotId`, seeded into each slot as its
-     * `defaultValue`. This is the other half of resume: `AttemptState.responses`
-     * goes straight in.
-     *
-     * Read at mount only. To restore a different attempt, remount with a `key`.
-     */
-    responses?: Readonly<Record<string, LearnerResponse>>;
-    /**
-     * Slots the learner had already submitted, from `AttemptState.submittedSlotIds`.
-     * Each is mounted already submitted, so a resumed paper does not reopen a
-     * locked question as answerable — without this a learner can change and
-     * re-submit work they had already committed.
-     *
-     * Read at mount only, alongside `responses`.
-     */
-    submittedSlotIds?: readonly string[];
-    /**
-     * Server-computed outcomes keyed by `slotId`, forwarded to each slot. In
-     * `review` mode this is what marks correctness — the client never scores, so
-     * without it a review render has nothing to show.
-     */
-    outcomes?: Readonly<Record<string, ItemOutcome>>;
-    /** Renders author-supplied rich text; forwarded to the stimulus panel and every activity. */
-    sanitizeHtml?: HtmlSanitizer;
-    theme?: Partial<ThemeTokens>;
-    /**
-     * BCP 47 tag stamped as `lang` on this component's root. This is the
-     * INTERFACE language — the SDK's own chrome renders inside that element — so
-     * it should carry the same value you give `<LkIntlProvider locale>`. Passing
-     * a different one re-declares the language of every SDK string in this
-     * subtree without changing the words.
-     *
-     * It is NOT `data.locale`, which labels xAPI statements — and, on a
-     * dictation, places the dictation's own words: `<Dictation>` puts it, and
-     * the direction it names, on its title, hints, marks and solution. Other
-     * authored content in another language belongs on `stimulus.locale`, which
-     * `<StimulusPanel>` puts on the passage alone.
-     */
-    locale?: string;
-    disabled?: boolean;
-}
-declare function ActivitySequence({ activities, renderers, onActivityComplete, onComplete, onFinished, onSubmit, onInteraction, renderMode, shuffle, shuffleSeed, defaultIndex, onIndexChange, responses, submittedSlotIds, outcomes, sanitizeHtml, theme, locale, disabled, mediaBudget, recordingBinding, assessments, workletUrl, strings, ai, delivery, scoring, }: ActivitySequenceProps): React.JSX.Element;
-
-export { type ActivityRenderer, ActivitySequence, type ActivitySequenceProps, type SequenceItemOutcome, type SequenceQuestion };
+import { a as SequenceQuestion, i as SequenceItemOutcome, n as ActivitySequence, r as ActivitySequenceProps, t as ActivityRenderer } from "../index-6P4rJHrJ.cjs";
+export { type ActivityRenderer, ActivitySequence, type ActivitySequenceProps, type SequenceItemOutcome, type SequenceQuestion };