react-cheminfo 0.3.0 → 0.4.0

package/lib/pedagogy/core/progress.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Where the work a student did is kept, and how it is read back.
+ *
+ * The browser is the only binding there is by default; a course hosting its own
+ * service implements the same two calls and is plugged in instead, without
+ * anything else in the page knowing where the work went.
+ */
+import type { ExerciseStatus } from './types.ts';
+/** What is remembered about one exercise. */
+export interface ExerciseProgress {
+    status: ExerciseStatus;
+    /** What the student last wrote or drew, exactly as they left it. */
+    answer: string;
+    /**
+     * How many hints of the ladder were opened. A count, not a flag per hint:
+     * the ladder grows, and "solved with two hints" is what a student reads.
+     */
+    hintsRevealed: number;
+    /** Whether the sample answer is on screen. */
+    showSolution: boolean;
+}
+/** Everything a student has done, keyed by exercise id. */
+export type ProgressRecords<TProgress = ExerciseProgress> = Record<string, TProgress>;
+/**
+ * Where the results of the exercises are kept.
+ *
+ * A binding that answers over the network returns a promise from either call;
+ * what {@link ProgressStore.load} resolves to replaces whatever the page
+ * started from.
+ */
+export interface ProgressStore<TProgress = ExerciseProgress> {
+    /** How the binding names itself, for a sentence about it on the page. */
+    readonly name: string;
+    /** Give back everything that was stored. */
+    load: () => ProgressRecords<TProgress> | Promise<ProgressRecords<TProgress>>;
+    /** Keep everything, as it stands after a change. */
+    save: (records: ProgressRecords<TProgress>) => void | Promise<void>;
+}
+/**
+ * The record an exercise nobody has touched starts from.
+ * @returns A blank record.
+ */
+export declare function emptyProgress(): ExerciseProgress;
+/**
+ * Read one stored record over its defaults, field by field.
+ *
+ * A stored field is taken only when it has the same shape as its default, so a
+ * payload written by an older version of the page, or a corrupted one, falls
+ * back field by field rather than wholesale — and a field added after the last
+ * save simply keeps its default. A `null` default accepts anything.
+ * @param stored - Whatever came out of the store for this exercise.
+ * @param defaults - The record a fresh exercise starts from.
+ * @returns A complete record, with nothing unreadable carried over.
+ */
+export declare function mergeProgressRecord<TProgress extends object>(stored: unknown, defaults: TProgress): TProgress;
+/**
+ * Read one stored {@link ExerciseProgress}, with its two constrained fields
+ * checked rather than merely shape-matched: a status outside the three the
+ * page knows reads as `idle`, and a hint count that is negative or fractional
+ * reads as none revealed.
+ * @param stored - Whatever came out of the store for this exercise.
+ * @returns A record the page can trust.
+ */
+export declare function mergeExerciseProgress(stored: unknown): ExerciseProgress;
+/** What {@link localStorageProgressStore} is built from. */
+export interface LocalStorageProgressStoreOptions<TProgress> {
+    /** Namespace of the entry, without the version: `smiles:exercises`. */
+    key: string;
+    /**
+     * Bumped when the shape of a record changes, so a future shape can ignore
+     * today's entries instead of misreading them.
+     * @default 1
+     */
+    version?: number;
+    /**
+     * The record a fresh exercise starts from. When given, every stored record is
+     * read over it with {@link mergeProgressRecord}; when left out, a stored
+     * record is handed back as it was written.
+     * @default undefined
+     */
+    defaults?: TProgress;
+    /**
+     * How the binding names itself on the page.
+     * @default 'this browser'
+     */
+    name?: string;
+}
+/**
+ * Keep the work in `localStorage`, under one namespaced and versioned entry.
+ * @param options - Which entry to use, and what a fresh record looks like.
+ * @returns The binding, ready to be handed to the page.
+ */
+export declare function localStorageProgressStore<TProgress extends object>(options: LocalStorageProgressStoreOptions<TProgress>): ProgressStore<TProgress>;
+/** How far through a set of exercises a student is. */
+export interface ProgressSummary {
+    /** How many are right. */
+    solved: number;
+    /** How many were handed in and are not right yet. */
+    attempted: number;
+    /** How many there are to do. */
+    total: number;
+    /** `solved / total`, and 0 when there is nothing to do. */
+    ratio: number;
+}
+/**
+ * Count where a student stands, for the progress bar over a set.
+ * @param records - What the store gave back.
+ * @param ids - The exercises of the set being counted. Pass them whenever the
+ * bar must read against the whole set: without them only the exercises that
+ * were touched are counted, and the bar would sit at 100% on the first answer.
+ * @returns The counts and the ratio the bar is drawn from.
+ */
+export declare function progressSummary<TProgress extends {
+    status: ExerciseStatus;
+}>(records: ProgressRecords<TProgress>, ids?: readonly string[]): ProgressSummary;
+//# sourceMappingURL=progress.d.ts.map

package/lib/pedagogy/core/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../../src/pedagogy/core/progress.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,2DAA2D;AAC3D,MAAM,MAAM,eAAe,CAAC,SAAS,GAAG,gBAAgB,IAAI,MAAM,CAChE,MAAM,EACN,SAAS,CACV,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAAC,SAAS,GAAG,gBAAgB;IACzD,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,eAAe,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC,CAAC;IAC7E,oDAAoD;IACpD,IAAI,EAAE,CAAC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,gBAAgB,CAEhD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,SAAS,MAAM,EAC1D,MAAM,EAAE,OAAO,EACf,QAAQ,EAAE,SAAS,GAClB,SAAS,CAUX;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAQvE;AAED,4DAA4D;AAC5D,MAAM,WAAW,gCAAgC,CAAC,SAAS;IACzD,uEAAuE;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,SAAS,MAAM,EAChE,OAAO,EAAE,gCAAgC,CAAC,SAAS,CAAC,GACnD,aAAa,CAAC,SAAS,CAAC,CAsB1B;AAED,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,SAAS,SAAS;IAAE,MAAM,EAAE,cAAc,CAAA;CAAE,EAC1E,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,EACnC,GAAG,CAAC,EAAE,SAAS,MAAM,EAAE,GACtB,eAAe,CAWjB"}

package/lib/pedagogy/core/progress.js

@@ -0,0 +1,122 @@
+/**
+ * Where the work a student did is kept, and how it is read back.
+ *
+ * The browser is the only binding there is by default; a course hosting its own
+ * service implements the same two calls and is plugged in instead, without
+ * anything else in the page knowing where the work went.
+ */
+import { readJsonEntry, writeJsonEntry } from "./jsonStorage.js";
+/**
+ * The record an exercise nobody has touched starts from.
+ * @returns A blank record.
+ */
+export function emptyProgress() {
+    return { status: 'idle', answer: '', hintsRevealed: 0, showSolution: false };
+}
+/**
+ * Read one stored record over its defaults, field by field.
+ *
+ * A stored field is taken only when it has the same shape as its default, so a
+ * payload written by an older version of the page, or a corrupted one, falls
+ * back field by field rather than wholesale — and a field added after the last
+ * save simply keeps its default. A `null` default accepts anything.
+ * @param stored - Whatever came out of the store for this exercise.
+ * @param defaults - The record a fresh exercise starts from.
+ * @returns A complete record, with nothing unreadable carried over.
+ */
+export function mergeProgressRecord(stored, defaults) {
+    const merged = { ...defaults };
+    if (!isPlainRecord(stored))
+        return merged;
+    for (const [field, fallback] of Object.entries(defaults)) {
+        const value = stored[field];
+        if (value !== undefined && isSameShape(fallback, value)) {
+            merged[field] = value;
+        }
+    }
+    return merged;
+}
+/**
+ * Read one stored {@link ExerciseProgress}, with its two constrained fields
+ * checked rather than merely shape-matched: a status outside the three the
+ * page knows reads as `idle`, and a hint count that is negative or fractional
+ * reads as none revealed.
+ * @param stored - Whatever came out of the store for this exercise.
+ * @returns A record the page can trust.
+ */
+export function mergeExerciseProgress(stored) {
+    const merged = mergeProgressRecord(stored, emptyProgress());
+    return {
+        ...merged,
+        status: STATUSES.has(merged.status) ? merged.status : 'idle',
+        hintsRevealed: merged.hintsRevealed > 0 ? Math.floor(merged.hintsRevealed) : 0,
+    };
+}
+/**
+ * Keep the work in `localStorage`, under one namespaced and versioned entry.
+ * @param options - Which entry to use, and what a fresh record looks like.
+ * @returns The binding, ready to be handed to the page.
+ */
+export function localStorageProgressStore(options) {
+    const { key, version = 1, defaults, name = 'this browser' } = options;
+    const storageKey = `${key}:v${version}`;
+    return {
+        name,
+        load() {
+            const records = {};
+            const stored = readJsonEntry(storageKey);
+            if (!isPlainRecord(stored))
+                return records;
+            for (const [id, value] of Object.entries(stored)) {
+                if (!isPlainRecord(value))
+                    continue;
+                records[id] =
+                    defaults === undefined
+                        ? value
+                        : mergeProgressRecord(value, defaults);
+            }
+            return records;
+        },
+        save(records) {
+            writeJsonEntry(storageKey, records);
+        },
+    };
+}
+/**
+ * Count where a student stands, for the progress bar over a set.
+ * @param records - What the store gave back.
+ * @param ids - The exercises of the set being counted. Pass them whenever the
+ * bar must read against the whole set: without them only the exercises that
+ * were touched are counted, and the bar would sit at 100% on the first answer.
+ * @returns The counts and the ratio the bar is drawn from.
+ */
+export function progressSummary(records, ids) {
+    const keys = ids ?? Object.keys(records);
+    let solved = 0;
+    let attempted = 0;
+    for (const id of keys) {
+        const status = records[id]?.status;
+        if (status === 'solved')
+            solved++;
+        else if (status === 'attempted')
+            attempted++;
+    }
+    const total = keys.length;
+    return { solved, attempted, total, ratio: total === 0 ? 0 : solved / total };
+}
+const STATUSES = new Set([
+    'idle',
+    'attempted',
+    'solved',
+]);
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isSameShape(fallback, stored) {
+    if (fallback === null)
+        return true;
+    if (Array.isArray(fallback) !== Array.isArray(stored))
+        return false;
+    return typeof fallback === typeof stored && stored !== null;
+}
+//# sourceMappingURL=progress.js.map

package/lib/pedagogy/core/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../../../src/pedagogy/core/progress.ts"],"names":[],"mappings":"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"}

package/lib/pedagogy/core/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The spine every pedagogic tool shares: a level, a status, an exercise, a set
+ * of them, and one stop of a guided tour. What a given tool asks of a student
+ * differs — a regex, a SMILES, a formula — so those parts stay generic and the
+ * site adds them.
+ */
+/**
+ * How hard a step or an exercise is, which is also how it is coloured: green
+ * for a beginner, yellow for an intermediate, pink for an advanced one.
+ */
+export type ExerciseLevel = 'beginner' | 'intermediate' | 'advanced';
+/**
+ * Where a student stands on one exercise: never handed in, handed in and not
+ * right yet, or right. The three are exclusive — a solved exercise is no longer
+ * an attempted one.
+ */
+export type ExerciseStatus = 'idle' | 'attempted' | 'solved';
+/**
+ * What every exercise carries, whatever it asks for.
+ *
+ * A tool extends it with the shape of its own question and its own test cases.
+ */
+export interface BaseExercise {
+    /** Stable and URL-safe: it is what `/exercises/<id>` carries. */
+    id: string;
+    /** How the exercise is listed. */
+    title: string;
+    level: ExerciseLevel;
+    /** What to do, in a few sentences; may carry `[[term]]` markers. */
+    description: string;
+    /**
+     * Ordered from a nudge to almost the answer, revealed one at a time. Two to
+     * four is the useful range: never one, never six.
+     */
+    hints: string[];
+    /** A sample answer, shown only when the student asks to see it. */
+    solution: string;
+}
+/**
+ * A named list of exercises, which is what a link hands out.
+ *
+ * The exercise type is the tool's own, so a set of SMARTS questions and a set
+ * of LaTeX formulas are the same structure holding different questions.
+ */
+export interface ExerciseSet<TExercise = BaseExercise> {
+    /** Stable and URL-safe. */
+    id: string;
+    title: string;
+    /** One line on what the set drills. */
+    description: string;
+    /**
+     * The level of the set as a whole, when it has one. A set whose level is read
+     * off its questions rather than written down leaves it out.
+     * @default undefined
+     */
+    level?: ExerciseLevel;
+    exercises: TExercise[];
+}
+/**
+ * One stop in the guided tour, plus whatever the tool preloads into its live
+ * playground — a pattern and its flags, a SMILES, a structure and a layer.
+ *
+ * A step is a working configuration the student is free to edit, never a slide.
+ */
+export type TutorialStep<TPayload = unknown> = {
+    /** Stable and URL-safe: it is what a link to the step carries. */
+    id: string;
+    title: string;
+    /** One short paragraph; may carry `[[term]]` markers. */
+    description: string;
+    /** Which coloured group the step is listed under. */
+    level: ExerciseLevel;
+} & TPayload;
+//# sourceMappingURL=types.d.ts.map

package/lib/pedagogy/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/pedagogy/core/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,cAAc,GAAG,UAAU,CAAC;AAErE;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE7D;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,iEAAiE;IACjE,EAAE,EAAE,MAAM,CAAC;IACX,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,aAAa,CAAC;IACrB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW,CAAC,SAAS,GAAG,YAAY;IACnD,2BAA2B;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,SAAS,EAAE,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,QAAQ,GAAG,OAAO,IAAI;IAC7C,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAC;IACpB,qDAAqD;IACrD,KAAK,EAAE,aAAa,CAAC;CACtB,GAAG,QAAQ,CAAC"}

package/lib/pedagogy/core/types.js

@@ -0,0 +1,8 @@
+/**
+ * The spine every pedagogic tool shares: a level, a status, an exercise, a set
+ * of them, and one stop of a guided tour. What a given tool asks of a student
+ * differs — a regex, a SMILES, a formula — so those parts stay generic and the
+ * site adds them.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/pedagogy/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/pedagogy/core/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/lib/pedagogy/core/validation.d.ts

@@ -0,0 +1,79 @@
+/**
+ * The verdict on an answer, in the shape every tool reports it.
+ *
+ * An exercise is marked by running the answer against test cases, never by
+ * comparing it to a string: two people write one molecule, one regex or one
+ * formula the same way far less often than they write it differently.
+ */
+/** How one test case came out. */
+export interface TestCaseResult {
+    passed: boolean;
+    /**
+     * What happened, written the way a tutor would say it — `match was "cat",
+     * expected "cats"`, `not matched, but this one should be found`. It is the
+     * sentence the student reads when a case fails, so it names the value and
+     * what was wanted; never `assertion failed`.
+     */
+    reason: string;
+    /** What the answer actually produced, or `null` when it produced nothing. */
+    actual: string | null;
+}
+/**
+ * The verdict on one answer: whether it is right, and everything the page needs
+ * to say why not.
+ *
+ * A tool that carries more per case — which test case it was, whether it was a
+ * match or a replacement — extends {@link TestCaseResult} and passes its own
+ * type through.
+ */
+export interface ValidationResult<TCase extends TestCaseResult = TestCaseResult> {
+    passed: boolean;
+    /**
+     * The one thing that stopped the cases from running at all: an answer that
+     * does not compile, or an empty one. `null` when the answer ran, however
+     * badly it did.
+     */
+    error: string | null;
+    cases: TCase[];
+    /**
+     * The options the exercise requires and the answer does not carry — a regex
+     * flag, a stereo descriptor. Reported apart from the cases, because a student
+     * staring at half-passing tests has no way of guessing which one is missing.
+     */
+    missingOptions: string[];
+}
+/** What {@link finishValidation} needs beyond the cases themselves. */
+export interface FinishValidationOptions {
+    /**
+     * A message that stopped the cases from being meaningful.
+     * @default null
+     */
+    error?: string | null;
+    /**
+     * Required options the answer does not carry.
+     * @default []
+     */
+    missingOptions?: string[];
+}
+/**
+ * Turn the cases a validator ran into the verdict on the answer.
+ *
+ * The answer is right only when nothing failed: no error, no missing option,
+ * and every case passed. A list with no cases in it has nothing failing in it
+ * and therefore passes — a validator that could not run its cases reports
+ * {@link failedValidation} instead of an empty list.
+ * @param cases - Every case that was run, in the order the page lists them.
+ * @param options - The error and the missing options, when there are any.
+ * @returns The verdict.
+ */
+export declare function finishValidation<TCase extends TestCaseResult>(cases: TCase[], options?: FinishValidationOptions): ValidationResult<TCase>;
+/**
+ * The verdict on an answer that never ran — it does not compile, or there is
+ * nothing to mark yet.
+ * @param error - What to tell the student, in their words rather than the
+ * engine's whenever the engine's can be improved on.
+ * @param cases - The cases, when the page still lists them as not evaluated.
+ * @returns The verdict.
+ */
+export declare function failedValidation<TCase extends TestCaseResult>(error: string, cases?: TCase[]): ValidationResult<TCase>;
+//# sourceMappingURL=validation.d.ts.map

package/lib/pedagogy/core/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/pedagogy/core/validation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,kCAAkC;AAClC,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB,CAC/B,KAAK,SAAS,cAAc,GAAG,cAAc;IAE7C,MAAM,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,KAAK,EAAE,CAAC;IACf;;;;OAIG;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,uEAAuE;AACvE,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,cAAc,EAC3D,KAAK,EAAE,KAAK,EAAE,EACd,OAAO,GAAE,uBAA4B,GACpC,gBAAgB,CAAC,KAAK,CAAC,CASzB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,cAAc,EAC3D,KAAK,EAAE,MAAM,EACb,KAAK,GAAE,KAAK,EAAO,GAClB,gBAAgB,CAAC,KAAK,CAAC,CAEzB"}

package/lib/pedagogy/core/validation.js

@@ -0,0 +1,47 @@
+/**
+ * The verdict on an answer, in the shape every tool reports it.
+ *
+ * An exercise is marked by running the answer against test cases, never by
+ * comparing it to a string: two people write one molecule, one regex or one
+ * formula the same way far less often than they write it differently.
+ */
+/**
+ * Turn the cases a validator ran into the verdict on the answer.
+ *
+ * The answer is right only when nothing failed: no error, no missing option,
+ * and every case passed. A list with no cases in it has nothing failing in it
+ * and therefore passes — a validator that could not run its cases reports
+ * {@link failedValidation} instead of an empty list.
+ * @param cases - Every case that was run, in the order the page lists them.
+ * @param options - The error and the missing options, when there are any.
+ * @returns The verdict.
+ */
+export function finishValidation(cases, options = {}) {
+    const error = options.error ?? null;
+    const missingOptions = options.missingOptions ?? [];
+    return {
+        passed: error === null && missingOptions.length === 0 && allPassed(cases),
+        error,
+        cases,
+        missingOptions,
+    };
+}
+/**
+ * The verdict on an answer that never ran — it does not compile, or there is
+ * nothing to mark yet.
+ * @param error - What to tell the student, in their words rather than the
+ * engine's whenever the engine's can be improved on.
+ * @param cases - The cases, when the page still lists them as not evaluated.
+ * @returns The verdict.
+ */
+export function failedValidation(error, cases = []) {
+    return { passed: false, error, cases, missingOptions: [] };
+}
+function allPassed(cases) {
+    for (const testCase of cases) {
+        if (!testCase.passed)
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=validation.js.map

package/lib/pedagogy/core/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/pedagogy/core/validation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAyDH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAc,EACd,UAAmC,EAAE;IAErC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC;IACpC,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC;IACpD,OAAO;QACL,MAAM,EAAE,KAAK,KAAK,IAAI,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC;QACzE,KAAK;QACL,KAAK;QACL,cAAc;KACf,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAa,EACb,QAAiB,EAAE;IAEnB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;AAC7D,CAAC;AAED,SAAS,SAAS,CAAC,KAAgC;IACjD,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;IACrC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/lib/pedagogy/ui/ExerciseActions.d.ts

@@ -0,0 +1,74 @@
+import type { ReactElement, ReactNode } from 'react';
+export interface ExerciseActionsProps {
+    /**
+     * Records the attempt. Grading itself runs on every keystroke, so this
+     * button commits the verdict rather than producing it.
+     * @default undefined — no Check button
+     */
+    onCheck?: () => void;
+    /**
+     * Text of the Check button.
+     * @default 'Check'
+     */
+    checkLabel?: string;
+    /**
+     * Whether checking is impossible yet — nothing typed, nothing drawn.
+     * @default false
+     */
+    checkDisabled?: boolean;
+    /**
+     * Opens the next hint.
+     * @default undefined — no hint button; the ladder may carry its own
+     */
+    onRevealHint?: () => void;
+    /**
+     * How many hints are already open, for the button's count.
+     * @default 0
+     */
+    hintsRevealed?: number;
+    /**
+     * How many hints the exercise has, for the button's count.
+     * @default 0
+     */
+    hintCount?: number;
+    /**
+     * Shows or hides the sample answer. Never gated behind anything: getting
+     * stuck and reading the answer is part of how the intuition is built.
+     * @default undefined — no solution button
+     */
+    onToggleSolution?: () => void;
+    /**
+     * Whether the sample answer is on screen, which is what the button offers to
+     * undo.
+     * @default false
+     */
+    showSolution?: boolean;
+    /**
+     * Puts the exercise back to a blank answer, no hints and no solution.
+     * @default undefined — no Reset button
+     */
+    onReset?: () => void;
+    /**
+     * The buttons this tool adds — show the diagram, show the 3D view — rendered
+     * after the four standard ones.
+     * @default undefined
+     */
+    children?: ReactNode;
+    /**
+     * Class the row carries, so a site can reach it from its stylesheet.
+     * @default undefined
+     */
+    className?: string;
+}
+/**
+ * The row of controls under an exercise: Check, Reveal hint, the solution, and
+ * Reset.
+ *
+ * Every one of them is optional, because a tool that grades live has no Check
+ * and a tool with a single-field answer has no Reset — what matters is that the
+ * ones a tool does offer read the same and sit in the same order everywhere.
+ * @param props - The actions the exercise offers.
+ * @returns The row.
+ */
+export declare function ExerciseActions(props: ExerciseActionsProps): ReactElement;
+//# sourceMappingURL=ExerciseActions.d.ts.map

package/lib/pedagogy/ui/ExerciseActions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExerciseActions.d.ts","sourceRoot":"","sources":["../../../src/pedagogy/ui/ExerciseActions.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAiB,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEpE,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,YAAY,CA+CzE"}

package/lib/pedagogy/ui/ExerciseActions.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Button } from '@blueprintjs/core';
+/**
+ * The row of controls under an exercise: Check, Reveal hint, the solution, and
+ * Reset.
+ *
+ * Every one of them is optional, because a tool that grades live has no Check
+ * and a tool with a single-field answer has no Reset — what matters is that the
+ * ones a tool does offer read the same and sit in the same order everywhere.
+ * @param props - The actions the exercise offers.
+ * @returns The row.
+ */
+export function ExerciseActions(props) {
+    const { onCheck, checkLabel = 'Check', checkDisabled = false, onRevealHint, hintsRevealed = 0, hintCount = 0, onToggleSolution, showSolution = false, onReset, children, className, } = props;
+    return (_jsxs("div", { className: className, style: ROW_STYLE, children: [onCheck !== undefined && (_jsx(Button, { intent: "primary", icon: "tick", text: checkLabel, disabled: checkDisabled, onClick: onCheck })), onRevealHint !== undefined && (_jsx(Button, { icon: "lightbulb", text: `Reveal hint (${Math.min(hintsRevealed, hintCount)}/${hintCount})`, disabled: hintsRevealed >= hintCount, onClick: onRevealHint })), onToggleSolution !== undefined && (_jsx(Button, { icon: showSolution ? 'eye-off' : 'key', text: showSolution ? 'Hide solution' : 'Reveal solution', onClick: onToggleSolution })), onReset !== undefined && (_jsx(Button, { icon: "reset", text: "Reset", onClick: onReset })), children] }));
+}
+const ROW_STYLE = {
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: 6,
+};
+//# sourceMappingURL=ExerciseActions.js.map

package/lib/pedagogy/ui/ExerciseActions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExerciseActions.js","sourceRoot":"","sources":["../../../src/pedagogy/ui/ExerciseActions.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAiE3C;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2B;IACzD,MAAM,EACJ,OAAO,EACP,UAAU,GAAG,OAAO,EACpB,aAAa,GAAG,KAAK,EACrB,YAAY,EACZ,aAAa,GAAG,CAAC,EACjB,SAAS,GAAG,CAAC,EACb,gBAAgB,EAChB,YAAY,GAAG,KAAK,EACpB,OAAO,EACP,QAAQ,EACR,SAAS,GACV,GAAG,KAAK,CAAC;IAEV,OAAO,CACL,eAAK,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,aACxC,OAAO,KAAK,SAAS,IAAI,CACxB,KAAC,MAAM,IACL,MAAM,EAAC,SAAS,EAChB,IAAI,EAAC,MAAM,EACX,IAAI,EAAE,UAAU,EAChB,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,OAAO,GAChB,CACH,EACA,YAAY,KAAK,SAAS,IAAI,CAC7B,KAAC,MAAM,IACL,IAAI,EAAC,WAAW,EAChB,IAAI,EAAE,gBAAgB,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,SAAS,CAAC,IAAI,SAAS,GAAG,EACxE,QAAQ,EAAE,aAAa,IAAI,SAAS,EACpC,OAAO,EAAE,YAAY,GACrB,CACH,EACA,gBAAgB,KAAK,SAAS,IAAI,CACjC,KAAC,MAAM,IACL,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,EACtC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,iBAAiB,EACxD,OAAO,EAAE,gBAAgB,GACzB,CACH,EACA,OAAO,KAAK,SAAS,IAAI,CACxB,KAAC,MAAM,IAAC,IAAI,EAAC,OAAO,EAAC,IAAI,EAAC,OAAO,EAAC,OAAO,EAAE,OAAO,GAAI,CACvD,EACA,QAAQ,IACL,CACP,CAAC;AACJ,CAAC;AAED,MAAM,SAAS,GAAkB;IAC/B,OAAO,EAAE,MAAM;IACf,QAAQ,EAAE,MAAM;IAChB,GAAG,EAAE,CAAC;CACP,CAAC"}

package/lib/pedagogy/ui/ExerciseProgressHeader.d.ts

@@ -0,0 +1,43 @@
+import type { ReactElement, ReactNode } from 'react';
+import type { ProgressSummary } from '../core/progress.ts';
+export interface ExerciseProgressHeaderProps {
+    /** Where the student stands, as `progressSummary` counted it. */
+    summary: ProgressSummary;
+    /**
+     * Throws away every answer, every revealed hint and every solved exercise.
+     * Guarded by a dialog the student has to confirm.
+     * @default undefined — the header only reports, and offers no way to wipe
+     */
+    onClearAll?: () => void;
+    /**
+     * Text of the button that wipes the work.
+     * @default 'Clear all answers'
+     */
+    clearLabel?: string;
+    /**
+     * What the confirmation dialog says before the work is thrown away.
+     * @default a sentence saying what is lost and that there is no undo
+     */
+    clearWarning?: ReactNode;
+    /**
+     * Whether the button is dead — there is nothing stored to wipe.
+     * @default false
+     */
+    clearDisabled?: boolean;
+    /**
+     * Class the header carries, so a site can reach it from its stylesheet.
+     * @default undefined
+     */
+    className?: string;
+}
+/**
+ * How much of a set is solved, its bar, and the one way to wipe it.
+ *
+ * Wiping goes through a real dialog rather than `confirm()`: the button throws
+ * away a week of somebody's work, and a native prompt is both unstyled and
+ * dismissed by reflex.
+ * @param props - The counts, and what clearing does.
+ * @returns The header.
+ */
+export declare function ExerciseProgressHeader(props: ExerciseProgressHeaderProps): ReactElement;
+//# sourceMappingURL=ExerciseProgressHeader.d.ts.map

package/lib/pedagogy/ui/ExerciseProgressHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExerciseProgressHeader.d.ts","sourceRoot":"","sources":["../../../src/pedagogy/ui/ExerciseProgressHeader.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAiB,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,WAAW,2BAA2B;IAC1C,iEAAiE;IACjE,OAAO,EAAE,eAAe,CAAC;IACzB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,CAAC;IACzB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,2BAA2B,GACjC,YAAY,CA+Dd"}