react-cheminfo 0.2.0 → 0.4.0

package/src/pedagogy/core/progress.ts

@@ -0,0 +1,205 @@
+/**
+ * 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.ts';
+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 function emptyProgress(): ExerciseProgress {
+  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<TProgress extends object>(
+  stored: unknown,
+  defaults: TProgress,
+): TProgress {
+  const merged = { ...defaults } as Record<string, unknown>;
+  if (!isPlainRecord(stored)) return merged as TProgress;
+  for (const [field, fallback] of Object.entries(defaults)) {
+    const value = stored[field];
+    if (value !== undefined && isSameShape(fallback, value)) {
+      merged[field] = value;
+    }
+  }
+  return merged as 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 function mergeExerciseProgress(stored: unknown): ExerciseProgress {
+  const merged = mergeProgressRecord(stored, emptyProgress());
+  return {
+    ...merged,
+    status: STATUSES.has(merged.status) ? merged.status : 'idle',
+    hintsRevealed:
+      merged.hintsRevealed > 0 ? Math.floor(merged.hintsRevealed) : 0,
+  };
+}
+
+/** 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 function localStorageProgressStore<TProgress extends object>(
+  options: LocalStorageProgressStoreOptions<TProgress>,
+): ProgressStore<TProgress> {
+  const { key, version = 1, defaults, name = 'this browser' } = options;
+  const storageKey = `${key}:v${version}`;
+  return {
+    name,
+    load(): ProgressRecords<TProgress> {
+      const records: ProgressRecords<TProgress> = {};
+      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 as TProgress)
+            : mergeProgressRecord(value, defaults);
+      }
+      return records;
+    },
+    save(records: ProgressRecords<TProgress>): void {
+      writeJsonEntry(storageKey, records);
+    },
+  };
+}
+
+/** 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 function progressSummary<TProgress extends { status: ExerciseStatus }>(
+  records: ProgressRecords<TProgress>,
+  ids?: readonly string[],
+): ProgressSummary {
+  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: ReadonlySet<ExerciseStatus> = new Set([
+  'idle',
+  'attempted',
+  'solved',
+]);
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isSameShape(fallback: unknown, stored: unknown): boolean {
+  if (fallback === null) return true;
+  if (Array.isArray(fallback) !== Array.isArray(stored)) return false;
+  return typeof fallback === typeof stored && stored !== null;
+}

package/src/pedagogy/core/types.ts

@@ -0,0 +1,78 @@
+/**
+ * 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;

package/src/pedagogy/core/validation.ts

@@ -0,0 +1,109 @@
+/**
+ * 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 function finishValidation<TCase extends TestCaseResult>(
+  cases: TCase[],
+  options: FinishValidationOptions = {},
+): ValidationResult<TCase> {
+  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<TCase extends TestCaseResult>(
+  error: string,
+  cases: TCase[] = [],
+): ValidationResult<TCase> {
+  return { passed: false, error, cases, missingOptions: [] };
+}
+
+function allPassed(cases: readonly TestCaseResult[]): boolean {
+  for (const testCase of cases) {
+    if (!testCase.passed) return false;
+  }
+  return true;
+}

package/src/pedagogy/ui/ExerciseActions.tsx

@@ -0,0 +1,129 @@
+import { Button } from '@blueprintjs/core';
+import type { CSSProperties, 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 function ExerciseActions(props: ExerciseActionsProps): ReactElement {
+  const {
+    onCheck,
+    checkLabel = 'Check',
+    checkDisabled = false,
+    onRevealHint,
+    hintsRevealed = 0,
+    hintCount = 0,
+    onToggleSolution,
+    showSolution = false,
+    onReset,
+    children,
+    className,
+  } = props;
+
+  return (
+    <div className={className} style={ROW_STYLE}>
+      {onCheck !== undefined && (
+        <Button
+          intent="primary"
+          icon="tick"
+          text={checkLabel}
+          disabled={checkDisabled}
+          onClick={onCheck}
+        />
+      )}
+      {onRevealHint !== undefined && (
+        <Button
+          icon="lightbulb"
+          text={`Reveal hint (${Math.min(hintsRevealed, hintCount)}/${hintCount})`}
+          disabled={hintsRevealed >= hintCount}
+          onClick={onRevealHint}
+        />
+      )}
+      {onToggleSolution !== undefined && (
+        <Button
+          icon={showSolution ? 'eye-off' : 'key'}
+          text={showSolution ? 'Hide solution' : 'Reveal solution'}
+          onClick={onToggleSolution}
+        />
+      )}
+      {onReset !== undefined && (
+        <Button icon="reset" text="Reset" onClick={onReset} />
+      )}
+      {children}
+    </div>
+  );
+}
+
+const ROW_STYLE: CSSProperties = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: 6,
+};

package/src/pedagogy/ui/ExerciseProgressHeader.tsx

@@ -0,0 +1,135 @@
+import { Alert, Button, ProgressBar } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import { useState } 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 function ExerciseProgressHeader(
+  props: ExerciseProgressHeaderProps,
+): ReactElement {
+  const {
+    summary,
+    onClearAll,
+    clearLabel = 'Clear all answers',
+    clearWarning = DEFAULT_WARNING,
+    clearDisabled = false,
+    className,
+  } = props;
+  const [confirming, setConfirming] = useState(false);
+  const complete = summary.total > 0 && summary.solved === summary.total;
+
+  return (
+    <div className={className} style={ROOT_STYLE}>
+      <div style={ROW_STYLE}>
+        <span style={COUNT_STYLE}>
+          {`${summary.solved} / ${summary.total} solved`}
+        </span>
+        <span
+          style={PERCENT_STYLE}
+        >{`${Math.round(summary.ratio * 100)}%`}</span>
+        {onClearAll !== undefined && (
+          <Button
+            size="small"
+            variant="minimal"
+            intent="danger"
+            icon="trash"
+            text={clearLabel}
+            disabled={clearDisabled}
+            onClick={() => {
+              setConfirming(true);
+            }}
+          />
+        )}
+      </div>
+
+      <ProgressBar
+        animate={false}
+        stripes={false}
+        intent={complete ? 'success' : 'primary'}
+        value={summary.ratio}
+      />
+
+      {onClearAll !== undefined && (
+        <Alert
+          isOpen={confirming}
+          intent="danger"
+          icon="trash"
+          cancelButtonText="Keep my answers"
+          confirmButtonText="Clear everything"
+          onCancel={() => {
+            setConfirming(false);
+          }}
+          onConfirm={() => {
+            onClearAll();
+            setConfirming(false);
+          }}
+        >
+          {clearWarning}
+        </Alert>
+      )}
+    </div>
+  );
+}
+
+const DEFAULT_WARNING =
+  'This forgets every answer, every revealed hint and every solved exercise, on this browser. There is no undo.';
+
+const ROOT_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+};
+
+const ROW_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 8,
+};
+
+const COUNT_STYLE: CSSProperties = { fontWeight: 600 };
+
+const PERCENT_STYLE: CSSProperties = {
+  color: '#5b6875',
+  flex: '1 1 auto',
+  fontSize: 12,
+};