@doenet/assignment-viewer 0.1.0-alpha-15 → 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

@@ -1,9 +1,10 @@
 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, fetchExternalDoenetML, darkMode, showAnswerResponseMenu, answerResponseCountsByItem, includeVariantSelector: _includeVariantSelector, showTitle, itemWord, }: {
+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;
@@ -20,16 +21,83 @@ export declare function ActivityViewer({ source, flags: specifiedFlags, activity
     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?: "dark" | "light";
+    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;
@@ -100,4 +168,11 @@ declare type SingleDocSource = {
     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 { }