react-cheminfo 0.64.0 → 0.65.0

package/src/pedagogy/core/attempts.ts

@@ -0,0 +1,205 @@
+/**
+ * How far a student has got on a graded series, kept in this browser.
+ *
+ * Best effort and never a precondition: a framed page whose storage is
+ * partitioned still works, it just forgets. An attempt is keyed by tool, series
+ * and question, so a new series starts clean and a shared link reopens its own.
+ * The store is a plain subscribable value, so a page reads it with React's
+ * `useSyncExternalStore` or from a signal of its own, and the series components
+ * re-render on it without knowing which.
+ */
+
+import { persistBucket } from '../../state/core/persistBucket.ts';
+
+import type { ProgressRecords, ProgressStore } from './progress.ts';
+import { localStorageProgressStore } from './progress.ts';
+import type { ExerciseStatus } from './types.ts';
+
+/** One question as the student left it. */
+export interface Attempt {
+  /** Where the student stands on it. */
+  status: ExerciseStatus;
+  /** What was typed, or drawn, field by field. */
+  answers: Record<string, string>;
+  /** The answers as they were when last checked, so a change hides the verdict. */
+  checked: string | null;
+  /** How many hints of the ladder are open. */
+  hintsRevealed: number;
+  /** Whether the worked answer is on screen. */
+  showSolution: boolean;
+}
+
+/**
+ * What a question looks like before anything is typed into it.
+ * @returns A fresh attempt.
+ */
+export function emptyAttempt(): Attempt {
+  return {
+    status: 'idle',
+    answers: {},
+    checked: null,
+    hintsRevealed: 0,
+    showSolution: false,
+  };
+}
+
+/**
+ * The key an attempt is kept under.
+ * @param tool - The tool.
+ * @param seed - The series.
+ * @param question - The question's key in the tool's pool.
+ * @returns `tool/seed/question`.
+ */
+export function attemptKey(
+  tool: string,
+  seed: number,
+  question: string,
+): string {
+  return `${tool}/${seed}/${question}`;
+}
+
+/** What {@link createAttemptStore} is built from. */
+export interface AttemptStoreOptions {
+  /**
+   * The site, which namespaces both entries: `atoms` keeps its attempts under
+   * `atoms:attempts:v1` and the series each tool was last on under
+   * `atoms:seeds:v1`.
+   */
+  key: string;
+  /**
+   * Where the attempts are kept, for a course that keeps them itself.
+   * @default the browser's `localStorage`, under `<key>:attempts:v1`
+   */
+  binding?: ProgressStore<Attempt>;
+  /**
+   * Called when a save was refused because the store is full.
+   * @default undefined
+   */
+  onQuotaExceeded?: (error: unknown) => void;
+}
+
+/** The attempts of a site, and the series each of its tools was last on. */
+export interface AttemptStore {
+  /** Every attempt this browser remembers; a new object after each change. */
+  records: () => ProgressRecords<Attempt>;
+  /** Be told after each change; returns the function that stops it. */
+  subscribe: (listener: () => void) => () => void;
+  /** One question's attempt, or a fresh one. */
+  attemptFor: (key: string) => Attempt;
+  /** Change one attempt and keep it. */
+  updateAttempt: (key: string, change: Partial<Attempt>) => void;
+  /** Forget the attempts of some questions. */
+  clearAttempts: (keys: readonly string[]) => void;
+  /**
+   * Forget every series of a tool but one, so storage does not grow with every
+   * new series drawn.
+   */
+  forgetOtherSeries: (tool: string, seed: number) => void;
+  /** The series a tool was last on in this browser, or null. */
+  storedSeed: (tool: string) => number | null;
+  /** Remember the series a tool is on. */
+  storeSeed: (tool: string, seed: number) => void;
+}
+
+/**
+ * The attempts of a site's graded series, kept in this browser.
+ * @param options - The site's namespace, and where else to keep them.
+ * @returns The store.
+ */
+export function createAttemptStore(options: AttemptStoreOptions): AttemptStore {
+  const { key, onQuotaExceeded } = options;
+  const binding =
+    options.binding ??
+    localStorageProgressStore<Attempt>({
+      key: `${key}:attempts`,
+      version: 1,
+      defaults: emptyAttempt(),
+      onQuotaExceeded,
+    });
+  const seeds = persistBucket<Record<string, number>>({
+    key: `${key}:seeds`,
+    version: 1,
+    defaults: {},
+    onQuotaExceeded,
+  });
+  const listeners = new Set<() => void>();
+  let current: ProgressRecords<Attempt> = {};
+  // Kept in memory as well, so a framed page whose storage is blocked still
+  // reopens the series it is on for as long as it stays open.
+  let seedsByTool = seeds.read().value;
+
+  function publish(next: ProgressRecords<Attempt>, save: boolean): void {
+    current = next;
+    if (save) void binding.save(next);
+    for (const listener of listeners) listener();
+  }
+
+  const loaded = binding.load();
+  if (loaded instanceof Promise) {
+    void loaded.then(
+      (records) => {
+        publish(records, false);
+      },
+      () => {
+        // A binding that cannot answer leaves the page working from nothing.
+      },
+    );
+  } else {
+    current = loaded;
+  }
+
+  function attemptFor(attempt: string): Attempt {
+    return current[attempt] ?? emptyAttempt();
+  }
+
+  return {
+    records: () => current,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    attemptFor,
+    updateAttempt(attempt, change) {
+      publish(
+        { ...current, [attempt]: { ...attemptFor(attempt), ...change } },
+        true,
+      );
+    },
+    clearAttempts(keys) {
+      const cleared = new Set(keys);
+      publish(
+        keep(current, (attempt) => !cleared.has(attempt)),
+        true,
+      );
+    },
+    forgetOtherSeries(tool, seed) {
+      const kept = `${tool}/${seed}/`;
+      publish(
+        keep(
+          current,
+          (attempt) =>
+            !attempt.startsWith(`${tool}/`) || attempt.startsWith(kept),
+        ),
+        true,
+      );
+    },
+    storedSeed: (tool) => seedsByTool[tool] ?? null,
+    storeSeed(tool, seed) {
+      seedsByTool = { ...seedsByTool, [tool]: seed };
+      seeds.write(seedsByTool);
+    },
+  };
+}
+
+function keep(
+  records: ProgressRecords<Attempt>,
+  wanted: (key: string) => boolean,
+): ProgressRecords<Attempt> {
+  const next: ProgressRecords<Attempt> = {};
+  for (const [key, attempt] of Object.entries(records)) {
+    if (wanted(key)) next[key] = attempt;
+  }
+  return next;
+}

package/src/pedagogy/core/index.ts

@@ -40,3 +40,39 @@ export type {
   ValidationResult,
 } from './validation.ts';
 export { failedValidation, finishValidation } from './validation.ts';
+export {
+  emptyCase,
+  formatSigned,
+  readAnswerNumber,
+  unreadableCase,
+} from './answers.ts';
+export type { Attempt, AttemptStore, AttemptStoreOptions } from './attempts.ts';
+export { attemptKey, createAttemptStore, emptyAttempt } from './attempts.ts';
+export type {
+  ControlledProgress,
+  ProgressController,
+  ProgressControllerOptions,
+  ProgressSignal,
+} from './progressController.ts';
+export { createProgressController } from './progressController.ts';
+export type {
+  PickSeededOptions,
+  SeedDraw,
+  SeedRange,
+  SeedValue,
+} from './seed.ts';
+export {
+  EACH_SEED,
+  LARGEST_SEED,
+  freshSeed,
+  parseSeed,
+  pickSeeded,
+  seedParam,
+} from './seed.ts';
+export type {
+  AnswerCheck,
+  AnswerField,
+  Answers,
+  FieldCase,
+  SeriesTool,
+} from './series.ts';

package/src/pedagogy/core/progressController.ts

@@ -0,0 +1,116 @@
+/**
+ * The handful of actions every exercise page performs on the progress it keeps:
+ * read one record, mark it, open a hint, show the answer, forget it.
+ *
+ * The records live in whatever the page already holds its state in — a signal
+ * of `@preact/signals-react`, or anything with a writable `value` — and every
+ * action replaces that value rather than mutating it, so whatever renders from
+ * it is told.
+ */
+
+import type { ExerciseProgress, ProgressRecords } from './progress.ts';
+import { emptyProgress } from './progress.ts';
+import type { ExerciseStatus } from './types.ts';
+
+/** A writable box holding the records, which a signal is. */
+export interface ProgressSignal<TProgress> {
+  /** The records by exercise id; replaced, never mutated. */
+  value: ProgressRecords<TProgress>;
+}
+
+/** The least a record has to carry for the controller to act on it. */
+export interface ControlledProgress {
+  /** Where the student stands. */
+  status: ExerciseStatus;
+  /** How many hints are open. */
+  hintsRevealed: number;
+  /** Whether the sample answer is on screen. */
+  showSolution: boolean;
+}
+
+/** What {@link createProgressController} is built with. */
+export interface ProgressControllerOptions<TProgress> {
+  /**
+   * The record an exercise nobody has touched reads as.
+   * @default emptyProgress — status, answer, hints and solution
+   */
+  empty?: () => TProgress;
+}
+
+/** The actions on one page's progress. */
+export interface ProgressController<TProgress extends ControlledProgress> {
+  /** One exercise's record, defaults included; reads the signal. */
+  getExerciseProgress: (id: string) => TProgress;
+  /** Record an attempt or a success. */
+  setExerciseStatus: (id: string, status: ExerciseStatus) => void;
+  /** Change any fields of one record, the others kept. */
+  updateProgress: (id: string, patch: Partial<TProgress>) => void;
+  /**
+   * Open the next hint, one at a time, stopping at the last when the count is
+   * given.
+   */
+  revealNextHint: (id: string, hintCount?: number) => void;
+  /** Show or hide the sample answer. */
+  setShowSolution: (id: string, show: boolean) => void;
+  /** Forget one exercise. */
+  resetExercise: (id: string) => void;
+  /**
+   * Forget every exercise. The page puts this behind a confirmation dialog,
+   * because it wipes a week of a student's work.
+   */
+  clearAllProgress: () => void;
+}
+
+/**
+ * The actions on the progress a page keeps in a signal.
+ * @param progress - The signal holding the records by exercise id.
+ * @param options - What an untouched exercise reads as.
+ * @returns The actions.
+ */
+export function createProgressController<
+  TProgress extends ControlledProgress = ExerciseProgress,
+>(
+  progress: ProgressSignal<TProgress>,
+  options: ProgressControllerOptions<TProgress> = {},
+): ProgressController<TProgress> {
+  const empty = options.empty ?? (emptyProgress as unknown as () => TProgress);
+
+  function getExerciseProgress(id: string): TProgress {
+    return { ...empty(), ...progress.value[id] };
+  }
+
+  function updateProgress(id: string, patch: Partial<TProgress>): void {
+    progress.value = {
+      ...progress.value,
+      [id]: { ...getExerciseProgress(id), ...patch },
+    };
+  }
+
+  return {
+    getExerciseProgress,
+    updateProgress,
+    setExerciseStatus(id, status) {
+      updateProgress(id, { status } as Partial<TProgress>);
+    },
+    revealNextHint(id, hintCount) {
+      const revealed = getExerciseProgress(id).hintsRevealed + 1;
+      updateProgress(id, {
+        hintsRevealed:
+          hintCount === undefined ? revealed : Math.min(revealed, hintCount),
+      } as Partial<TProgress>);
+    },
+    setShowSolution(id, show) {
+      updateProgress(id, { showSolution: show } as Partial<TProgress>);
+    },
+    resetExercise(id) {
+      const next: ProgressRecords<TProgress> = {};
+      for (const [key, value] of Object.entries(progress.value)) {
+        if (key !== id) next[key] = value;
+      }
+      progress.value = next;
+    },
+    clearAllProgress() {
+      progress.value = {};
+    },
+  };
+}

package/src/pedagogy/core/seed.ts

@@ -0,0 +1,177 @@
+/**
+ * The seed a series is drawn from, and the drawing itself.
+ *
+ * A series is a link: `?seed=4271` hands the same questions, in the same order,
+ * to everybody who opens it, on every machine and in every browser. So the
+ * drawing goes through `ml-xsadd` and nothing else — a hand-rolled generator
+ * silently changes its sequence the day somebody improves it, and every link
+ * that pinned a seed then opens a different problem set.
+ */
+
+import { XSadd } from 'ml-xsadd';
+
+import type { ShareParamCodec } from '../../share/core/params.ts';
+
+/** The largest seed a link may carry: an unsigned 32-bit integer. */
+export const LARGEST_SEED = 2 ** 32 - 1;
+
+/** The seeds a link may pin, both ends included. */
+export interface SeedRange {
+  /** The smallest seed. */
+  min: number;
+  /** The largest seed. */
+  max: number;
+}
+
+/**
+ * Which call of the generator a shuffle draws from. Both are reproducible; they
+ * are two different sequences, so a site keeps the one its links were written
+ * with.
+ */
+export type SeedDraw = 'getFloat' | 'getUint32';
+
+/** How {@link pickSeeded} draws. */
+export interface PickSeededOptions {
+  /**
+   * The generator call the shuffle is driven by: `getFloat`, scaled to the
+   * remaining positions, or `getUint32`, taken modulo them.
+   * @default 'getFloat'
+   */
+  draw?: SeedDraw;
+  /**
+   * Whether a series longer than the pool goes round it again, so it is always
+   * exactly as long as asked. Otherwise it stops at the pool.
+   * @default false
+   */
+  wrap?: boolean;
+}
+
+/**
+ * Pick `count` items out of a pool, the same ones in the same order for the
+ * same seed.
+ *
+ * The pool is shuffled by Fisher–Yates driven by XSadd and the series is the
+ * head of that shuffle, so asking for more questions from the same seed keeps
+ * the ones already on screen. The pool itself is never reordered.
+ * @param pool - Everything a series can draw from.
+ * @param count - How many to take; more than the pool holds takes them all,
+ * or goes round again with `wrap`.
+ * @param seed - An unsigned 32-bit integer.
+ * @param options - Which generator call drives the shuffle, and whether the
+ * series wraps.
+ * @returns The picked items, in drawn order.
+ */
+export function pickSeeded<T>(
+  pool: readonly T[],
+  count: number,
+  seed: number,
+  options: PickSeededOptions = {},
+): T[] {
+  const { draw = 'getFloat', wrap = false } = options;
+  const order = shuffledOrder(pool.length, seed, draw);
+  const wanted = Math.max(0, Math.trunc(count));
+  const size =
+    pool.length === 0 ? 0 : wrap ? wanted : Math.min(wanted, pool.length);
+  const picked = new Array<T>(size);
+  for (let index = 0; index < size; index++) {
+    picked[index] = pool[order[index % order.length] as number] as T;
+  }
+  return picked;
+}
+
+/**
+ * A seed for a series nobody has asked for yet.
+ *
+ * `ml-xsadd` unseeded rather than `Math.random`, so the one generator the page
+ * draws from is the one every link pins.
+ * @param range - The seeds a link may carry, so a drawn one is one of them.
+ * @default range { min: 0, max: LARGEST_SEED }
+ * @returns A whole number inside the range.
+ */
+export function freshSeed(range?: SeedRange): number {
+  const drawn = new XSadd().getUint32();
+  if (range === undefined) return drawn;
+  const span = range.max - range.min + 1;
+  return range.min + (drawn % span);
+}
+
+/**
+ * Read a seed out of an address, strictly: anything that is not a whole number
+ * inside the range reads as no seed at all.
+ * @param raw - The `seed` parameter, as typed or as a link carries it.
+ * @param range - The seeds a link may carry.
+ * @default range { min: 0, max: LARGEST_SEED }
+ * @returns The seed, or null when the parameter is absent or not one.
+ */
+export function parseSeed(
+  raw: string | null | undefined,
+  range?: SeedRange,
+): number | null {
+  if (raw === null || raw === undefined || !/^\d{1,10}$/u.test(raw)) {
+    return null;
+  }
+  const seed = Number(raw);
+  const { min = 0, max = LARGEST_SEED } = range ?? {};
+  return seed >= min && seed <= max ? seed : null;
+}
+
+/** What a link writes to ask for a series per student rather than one per class. */
+export const EACH_SEED = 'each';
+
+/**
+ * What `?seed=` can say: a pinned series, a series per student, or no series —
+ * `null` rather than a number for the last, because `0` is a seed somebody may
+ * pin.
+ */
+export type SeedValue = number | typeof EACH_SEED | null;
+
+/**
+ * The codec of a `?seed=` that also understands `each`.
+ *
+ * A number is a problem set handed to a whole class; `each` is one link under
+ * which no two students work on the same set, the site drawing one seed per
+ * browser the first time it opens. A number outside the range is brought back
+ * inside it, and anything else reads as no series, so a hand-edited
+ * `?seed=today` still opens something.
+ * @param range - The seeds a link may pin.
+ * @returns The codec.
+ */
+export function seedParam(range: SeedRange): ShareParamCodec<SeedValue> {
+  return {
+    parse(raw) {
+      if (raw === null) return null;
+      const text = raw.trim();
+      if (text === '') return null;
+      if (text.toLowerCase() === EACH_SEED) return EACH_SEED;
+      const parsed = Number(text);
+      if (Number.isNaN(parsed)) return null;
+      return clampSeed(parsed, range);
+    },
+    serialize(value) {
+      if (value === EACH_SEED) return EACH_SEED;
+      if (typeof value !== 'number') return null;
+      return String(clampSeed(value, range));
+    },
+  };
+}
+
+function clampSeed(value: number, range: SeedRange): number {
+  if (!Number.isFinite(value)) return range.min;
+  return Math.min(range.max, Math.max(range.min, Math.round(value)));
+}
+
+function shuffledOrder(length: number, seed: number, draw: SeedDraw): number[] {
+  const generator = new XSadd(seed);
+  const order = new Array<number>(length);
+  for (let index = 0; index < length; index++) order[index] = index;
+  for (let index = length - 1; index > 0; index--) {
+    const other =
+      draw === 'getUint32'
+        ? generator.getUint32() % (index + 1)
+        : Math.floor(generator.getFloat() * (index + 1));
+    const kept = order[index] as number;
+    order[index] = order[other] as number;
+    order[other] = kept;
+  }
+  return order;
+}

package/src/pedagogy/core/series.ts

@@ -0,0 +1,82 @@
+/**
+ * A graded series: questions drawn from a tool's pool by a seed, each asking
+ * the student to fill a few boxes, each box graded as a test case.
+ *
+ * Nothing here knows what is asked — electrons, a formula, a mass — so a tool
+ * of any subject describes its questions with {@link SeriesTool} and the shared
+ * series components draw them.
+ */
+
+import type { ExerciseLevel } from './types.ts';
+import type { TestCaseResult, ValidationResult } from './validation.ts';
+
+/** What a student has typed into a question, field by field. */
+export type Answers = Readonly<Record<string, string>>;
+
+/** One box a question asks the student to fill. */
+export interface AnswerField {
+  /** Key of the value in {@link Answers}. */
+  key: string;
+  /** What the box is for, e.g. `Electrons` or `³⁵Cl (%)`. */
+  label: string;
+  /**
+   * Placeholder written in the empty box.
+   * @default undefined
+   */
+  placeholder?: string;
+  /**
+   * The keyboard a phone opens for the box: digits for a number, letters for
+   * a name or a formula.
+   * @default 'decimal'
+   */
+  inputMode?: 'decimal' | 'text';
+}
+
+/** The verdict on one field of an answer. */
+export interface FieldCase extends TestCaseResult {
+  /** The field the verdict is about, as the box labels it. */
+  label: string;
+}
+
+/** The verdict on a whole answer. */
+export type AnswerCheck = ValidationResult<FieldCase>;
+
+/**
+ * One tool's exercises: the pool a series is drawn from, what a question asks
+ * for, and how an answer is graded, hinted at and solved. Pure: nothing here
+ * renders, so every part is unit-tested.
+ */
+export interface SeriesTool<Question> {
+  /** Where the tool's progress and seed are kept. */
+  id: string;
+  /** Every question a series can draw. */
+  pool: readonly Question[];
+  /** A stable key for a question, unique in the pool. */
+  key: (question: Question) => string;
+  /**
+   * The level a question is tagged with.
+   * @default undefined
+   */
+  level?: (question: Question) => ExerciseLevel;
+  /** The boxes the question asks the student to fill. */
+  fields: (question: Question) => AnswerField[];
+  /** Grade an answer, one case per field, each reason written as a tutor says it. */
+  grade: (question: Question, answers: Answers) => AnswerCheck;
+  /** Two to four hints, vague to nearly the answer. */
+  hints: (question: Question) => string[];
+  /** The worked answer, always revealable. */
+  solution: (question: Question) => string;
+  /**
+   * Draw the series itself, for a tool whose questions are generated from the
+   * seed rather than picked out of {@link SeriesTool.pool}. It must return the
+   * same questions in the same order for the same seed, since a series is a
+   * link.
+   * @default undefined — the series is `pickSeeded(pool, count, seed)`
+   */
+  draw?: (count: number, seed: number) => readonly Question[];
+  /**
+   * The longest series the tool can serve, for the picker of its length.
+   * @default the size of the pool
+   */
+  maxCount?: number;
+}

package/src/pedagogy/ui/AnswerFields.tsx

@@ -0,0 +1,63 @@
+import { FormGroup, InputGroup } from '@blueprintjs/core';
+import type { KeyboardEvent, ReactElement } from 'react';
+import { useId } from 'react';
+
+import type { AnswerField, Answers } from '../core/series.ts';
+
+/** What {@link AnswerFields} needs. */
+export interface AnswerFieldsProps {
+  /** The boxes the question asks for, in the order they are filled. */
+  fields: readonly AnswerField[];
+  /** What is typed in them so far. */
+  answers: Answers;
+  /** Called with the key of a box and its new text on every keystroke. */
+  onChange: (key: string, value: string) => void;
+  /** Called on Enter, which checks the answer. */
+  onSubmit: () => void;
+}
+
+/**
+ * The boxes a question asks the student to fill, side by side, each with the
+ * keyboard its value wants on a phone and every autocorrection switched off.
+ * @param props - The fields, what is typed in them, and what to do on a change.
+ * @returns The boxes.
+ */
+export function AnswerFields(props: AnswerFieldsProps): ReactElement {
+  const { fields, answers, onChange, onSubmit } = props;
+  const prefix = useId();
+
+  function submitOnEnter(event: KeyboardEvent<HTMLInputElement>): void {
+    if (event.key === 'Enter') onSubmit();
+  }
+
+  return (
+    <div className="series-answers">
+      {fields.map((field) => {
+        const id = `${prefix}-${field.key}`;
+        return (
+          <FormGroup
+            key={field.key}
+            label={field.label}
+            labelFor={id}
+            className="series-answers__field"
+          >
+            <InputGroup
+              id={id}
+              value={answers[field.key] ?? ''}
+              placeholder={field.placeholder}
+              onValueChange={(value) => {
+                onChange(field.key, value);
+              }}
+              onKeyDown={submitOnEnter}
+              inputMode={field.inputMode ?? 'decimal'}
+              autoComplete="off"
+              autoCorrect="off"
+              autoCapitalize="off"
+              spellCheck={false}
+            />
+          </FormGroup>
+        );
+      })}
+    </div>
+  );
+}