@doenet/assignment-viewer 0.1.0-alpha-14 → 0.1.0-alpha-16

package/README.md

@@ -1,3 +1,70 @@
 # Doenet assignment viewer
 
 View assignments from questions written in DoenetML
+
+## Mixed DoenetML versions
+
+Each document in an assignment carries its own DoenetML `version`, and every
+embedded viewer downloads and parses the multi-MB standalone bundle for its
+document's version — so an assignment mixing versions multiplies that cost
+by the number of distinct versions on the page.
+
+The viewer does not normalize versions itself (that would change how the
+older documents behave). Instead, when an assignment mixes versions, it
+reports the condition to the containing page — a console warning alone would
+be invisible to the site's visitors — via the `reportWarningsCallback` prop,
+and the page decides how to display it:
+
+```tsx
+<ActivityViewer
+    source={source}
+    reportWarningsCallback={(warnings) => {
+        for (const warning of warnings) {
+            if (warning.type === "mixedDoenetmlVersions") {
+                showBanner(
+                    `This assignment mixes DoenetML versions (${warning.versions.join(", ")}), ` +
+                        "which slows loading. Consider updating its documents to one version.",
+                );
+            }
+        }
+    }}
+/>
+```
+
+To consolidate, normalize the documents' `version` fields in the assignment
+source. Saved student state survives such a change: it is keyed on a source
+hash that deliberately ignores `version`.
+
+## Windowed mounting
+
+Every item's viewer component is always mounted, but memory tracks what the
+student can see — the pagination window or viewport — instead of the
+assignment's length. The embedded viewers register with a page-wide
+_windowed mounting_ policy (`mountPolicy` from `@doenet/doenetml-iframe`):
+items only boot their iframe (a multi-MB bundle parse plus a core worker)
+when near the viewport or within the pagination window, simultaneous boots
+are capped, and at most `maxLiveViewers` stay live — the rest are **parked**:
+their state is flushed, their iframe is replaced by a placeholder, and they
+are restored (student's typed work intact) when the student returns to them.
+In paginated mode the current page and its neighbors are kept live, so page
+flips within the window stay instant.
+
+This is the default. Tune it with the `mountPolicy` prop (overrides for
+`maxLiveViewers`, `visibleMargin`, `parkDelayMs`, `flushTimeoutMs`,
+`maxConcurrentBoots`):
+
+```tsx
+<ActivityViewer
+    source={source}
+    flags={{ allowSaveState: true }}
+    mountPolicy={{ maxLiveViewers: 5 }}
+/>
+```
+
+Parking requires a persistence path (`flags.allowSaveState` or
+`flags.allowLocalState`) so no student work can be lost; without one,
+viewers still mount lazily but stay live once booted.
+
+To cut the per-document core cost further, `useSharedCoreWorker` serves all
+documents' cores from a shared worker pool instead of one dedicated ~100 MB
+worker per document (default off; see `@doenet/doenetml-iframe`).

package/dist/assignment-viewer.css

@@ -0,0 +1,29 @@
+.assignment-viewer-root {
+    --canvas: white;
+    --canvasText: black;
+    --mainGray: #e3e3e3;
+    --mainBorder: 2px solid black;
+    --mainBorderRadius: 5px;
+    --buttonSurface: #e3e3e3;
+    --buttonSurfaceAlt: rgb(237, 242, 247);
+}
+
+.assignment-viewer-root[data-theme="dark"] {
+    --canvas: #121212;
+    --canvasText: white;
+    --mainGray: #a9a9a9;
+    --mainBorder: 2px solid white;
+    --buttonSurface: #3a3a3a;
+    --buttonSurfaceAlt: #2d3748;
+}
+
+.assignment-viewer-root {
+    background-color: var(--canvas);
+    color: var(--canvasText);
+}
+
+/* Give iframes the canvas background color so there's no white flash
+   while the standalone bundle loads its own dark-mode styles. */
+.assignment-viewer-root iframe {
+    background-color: var(--canvas);
+}

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+import { JSX } from 'react/jsx-runtime';
+import { MountPolicy } from '@doenet/doenetml-iframe';
+
+/** The source for creating an activity */
+export declare type ActivitySource = SingleDocSource | SelectSource | SequenceSource;
+
+export declare function ActivityViewer({ source, flags: specifiedFlags, activityId, userId, requestedVariantIndex, maxAttemptsAllowed, itemLevelAttempts, activityLevelAttempts, paginate, showFinishButton, forceDisable, forceShowCorrectness, forceShowSolution, forceUnsuppressCheckwork, addVirtualKeyboard, externalVirtualKeyboardProvided, doenetViewerUrl, doenetImagesUrl, standaloneUrl, cssUrl, doenetmlVersion, fetchExternalDoenetML, darkMode, showAnswerResponseMenu, answerResponseCountsByItem, includeVariantSelector: _includeVariantSelector, showTitle, itemWord, reportWarningsCallback, mountPolicy, useSharedCoreWorker, }: {
+    source: ActivitySource;
+    flags?: DoenetMLFlagsSubset;
+    activityId?: string;
+    userId?: string | null;
+    requestedVariantIndex?: number;
+    maxAttemptsAllowed?: number;
+    itemLevelAttempts?: boolean;
+    activityLevelAttempts?: boolean;
+    paginate?: boolean;
+    showFinishButton?: boolean;
+    forceDisable?: boolean;
+    forceShowCorrectness?: boolean;
+    forceShowSolution?: boolean;
+    forceUnsuppressCheckwork?: boolean;
+    addVirtualKeyboard?: boolean;
+    externalVirtualKeyboardProvided?: boolean;
+    /**
+     * URL the `<ref>` renderer uses to build links to other Doenet
+     * activities. Forwarded to each document's viewer, which defaults it to
+     * `https://doenet.org/activityViewer`.
+     */
+    doenetViewerUrl?: string;
+    /**
+     * URL used to resolve `<image source="doenet:…">` media references.
+     * Forwarded to each document's viewer, which defaults it to
+     * `https://doenet.org/api/media`.
+     */
+    doenetImagesUrl?: string;
+    /**
+     * URL of a standalone DoenetML bundle to use for every document,
+     * instead of the CDN bundle for each document's `version`.
+     */
+    standaloneUrl?: string;
+    /** URL of the CSS file that styles the standalone bundle. */
+    cssUrl?: string;
+    /**
+     * Render every document with this DoenetML version, overriding each
+     * document's own `version`.
+     */
+    doenetmlVersion?: string;
+    fetchExternalDoenetML?: (arg: string) => Promise<string>;
+    darkMode?: ThemeSetting;
+    showAnswerResponseMenu?: boolean;
+    answerResponseCountsByItem?: Record<string, number>[];
+    includeVariantSelector?: boolean;
+    showTitle?: boolean;
+    itemWord?: string;
+    /**
+     * Called with conditions in `source` worth surfacing to the user, e.g.
+     * an assignment mixing DoenetML versions. Invoked once per distinct set
+     * of warnings — not on every render, and not again when the consumer
+     * passes a fresh-but-equal `source` each render. The containing page
+     * decides how to display them; a `console.warn` is also emitted for
+     * developers.
+     */
+    reportWarningsCallback?: (warnings: ActivityViewerWarning[]) => void;
+    /**
+     * Overrides for the windowed mounting policy every document's viewer
+     * registers with (see `MountPolicy` in `@doenet/doenetml-iframe`):
+     * at most `maxLiveViewers` viewers stay booted, the rest are parked
+     * losslessly as placeholders and restored near the viewport. Parking
+     * requires `flags.allowSaveState` or `flags.allowLocalState`; without
+     * them viewers still mount lazily but stay live once booted.
+     */
+    mountPolicy?: Partial<Omit<MountPolicy, "mode">>;
+    /**
+     * Serve all documents' cores from a shared worker pool instead of one
+     * dedicated ~100 MB worker per document (see `useSharedCoreWorker` in
+     * `@doenet/doenetml-iframe`). Default off.
+     */
+    useSharedCoreWorker?: boolean;
+}): JSX.Element | null;
+
+/**
+ * A condition in the provided activity worth surfacing to the user — passed
+ * to `reportWarningsCallback`, since a console warning is invisible to the
+ * site's visitors. How (and whether) to display it is the containing page's
+ * decision.
+ */
+export declare type ActivityViewerWarning = {
+    type: "mixedDoenetmlVersions";
+    /**
+     * The distinct DoenetML versions the assignment's documents request, in
+     * first-appearance order. Every embedded viewer downloads and parses
+     * the multi-MB standalone bundle for its document's version, so mixing
+     * versions multiplies that cost by the number of distinct versions.
+     * (Normalizing the `version` fields in the source avoids it; saved
+     * student state is keyed on a hash that ignores `version`, so it
+     * survives such a change.)
+     */
+    versions: string[];
+};
+
+declare type DoenetMLFlags = {
+    showCorrectness: boolean;
+    readOnly: boolean;
+    solutionDisplayMode: string;
+    showFeedback: boolean;
+    showHints: boolean;
+    allowLoadState: boolean;
+    allowSaveState: boolean;
+    allowLocalState: boolean;
+    allowSaveSubmissions: boolean;
+    allowSaveEvents: boolean;
+    autoSubmit: boolean;
+};
+
+declare type DoenetMLFlagsSubset = Partial<DoenetMLFlags>;
+
+export declare function isActivitySource(obj: unknown): obj is ActivitySource;
+
+/** The source for creating a select activity */
+declare type SelectSource = {
+    type: "select";
+    id: string;
+    title?: string;
+    /** The child activities to select from */
+    items: ActivitySource[];
+    /** The number of child activities to select (without replacement) for each attempt */
+    numToSelect: number;
+    /**
+     * Whether or not to consider each variant of each child a separate option to select from.
+     * If `selectByVariant` is `true`, the selection is from the total set of all variants,
+     * meaning selection probabilities is weighted by the number of variants each child has,
+     * and, if `numToSelect` > 1, a child could be selected multiple times for a given attempt.
+     */
+    selectByVariant: boolean;
+};
+
+/** The source for creating a sequence activity */
+declare type SequenceSource = {
+    type: "sequence";
+    id: string;
+    title?: string;
+    /** The child activities that form the sequence. */
+    items: ActivitySource[];
+    /** If `true`, randomly permute the item order on each new attempt. */
+    shuffle: boolean;
+    /**
+     * Weights given to the credit achieved of each item
+     * when averaging them to determine the credit achieved of the sequence activity.
+     * Items missing a weight are given the weight 1.
+     */
+    creditWeights?: number[];
+};
+
+/** The source for creating a single doc activity */
+declare type SingleDocSource = {
+    type: "singleDoc";
+    id: string;
+    title?: string;
+    /**
+     * If `isDescription` is `true`, then this activity is not considered one of the scored items
+     * and its credit achieved is ignored.
+     */
+    isDescription: boolean;
+    doenetML: string;
+    /** The version of DoenetML that should be used to render this activity. */
+    version: string;
+    /** The number of variants present in `doenetML` */
+    numVariants?: number;
+};
+
+/**
+ * `ThemeSetting` is the public, author-facing value of the `darkMode` prop:
+ * `"light"` and `"dark"` pin a specific theme, while `"system"` follows the
+ * OS/browser `prefers-color-scheme` preference and updates live.
+ */
+export declare type ThemeSetting = "dark" | "light" | "system";
+
+export { }