react-cheminfo 0.64.1 → 0.66.0

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>
+  );
+}

package/src/pedagogy/ui/ExerciseList.tsx

@@ -0,0 +1,202 @@
+import { Tag } from '@blueprintjs/core';
+import type { ReactElement, ReactNode } from 'react';
+
+import { useDocumentListNavigation } from '../../hooks/ui/useDocumentListNavigation.ts';
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+import type { ProgressRecords } from '../core/progress.ts';
+import { progressSummary } from '../core/progress.ts';
+import type { ExerciseLevel, ExerciseStatus } from '../core/types.ts';
+
+import { ExerciseProgressHeader } from './ExerciseProgressHeader.tsx';
+import { ExerciseLevelTag, ExerciseStatusIcon } from './ExerciseTags.tsx';
+import { InlineText } from './InlineText.tsx';
+
+/** What a row of the list reads off an exercise. */
+export interface ExerciseListEntry {
+  /** Stable id, which is what is selected. */
+  id: string;
+  /** How the exercise is named; may carry the shared prose marks. */
+  title: string;
+  /**
+   * How hard it is, drawn as a coloured tag.
+   * @default undefined — no level tag
+   */
+  level?: ExerciseLevel;
+}
+
+/** What the list reads of the progress kept on one exercise. */
+export interface ExerciseListProgress {
+  /** Where the student stands. */
+  status: ExerciseStatus;
+  /** How many hints were opened. */
+  hintsRevealed: number;
+}
+
+/** What {@link ExerciseList} needs. */
+export interface ExerciseListProps<TExercise extends ExerciseListEntry> {
+  /** The exercises, in the order they are worked through. */
+  exercises: readonly TExercise[];
+  /** The progress kept, by exercise id; an absent one reads as untouched. */
+  progress: ProgressRecords<ExerciseListProgress>;
+  /** The exercise on screen, or `null` for none. */
+  activeId: string | null;
+  /** Called with the id of the exercise to open. */
+  onSelect: (id: string) => void;
+  /**
+   * Tags of the tool's own after the level — the kind of question, say.
+   * @default undefined
+   */
+  tags?: (exercise: TExercise) => ReactNode;
+  /**
+   * Draws the title the tool's own way.
+   * @default the title as inline prose, its marks drawn
+   */
+  renderTitle?: (exercise: TExercise) => ReactNode;
+  /**
+   * Whether the bar of solved exercises heads the list.
+   * @default true
+   */
+  progressHeader?: boolean;
+  /**
+   * Throws away every answer, behind a dialog. Without it the header only
+   * reports.
+   * @default undefined
+   */
+  onClearAll?: () => void;
+  /**
+   * What the dialog says before the work is thrown away.
+   * @default the header's own sentence
+   */
+  clearWarning?: ReactNode;
+  /**
+   * What a screen reader calls the list.
+   * @default the chrome's own word for it, in the language of the page
+   */
+  label?: string;
+  /**
+   * Class the list carries, in addition to `exercise-list`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+const STATUS_TITLE: Record<ExerciseStatus, ChromeKey> = {
+  idle: 'pedagogy.statusIdle',
+  attempted: 'pedagogy.statusAttempted',
+  solved: 'pedagogy.statusSolved',
+};
+
+/**
+ * The exercises of a set, each with where the student stands on it, under the
+ * bar of how many are solved.
+ *
+ * The hint count of a solved exercise is shown rather than hidden: it is the
+ * honest record of which ones were hard, which is what a student coming back a
+ * week later wants to know. `ArrowUp` and `ArrowDown` walk the list from
+ * anywhere on the page, unless a text field has the focus.
+ * @param props - The exercises, their progress, and the open one.
+ * @returns The list.
+ */
+export function ExerciseList<TExercise extends ExerciseListEntry>(
+  props: ExerciseListProps<TExercise>,
+): ReactElement {
+  const {
+    exercises,
+    progress,
+    activeId,
+    onSelect,
+    tags,
+    renderTitle,
+    progressHeader = true,
+    onClearAll,
+    clearWarning,
+    label,
+    className,
+  } = props;
+  const t = useChromeT();
+  const activeIndex = exercises.findIndex(
+    (exercise) => exercise.id === activeId,
+  );
+  const listRef = useDocumentListNavigation<HTMLDivElement>({
+    length: exercises.length,
+    selectedIndex: activeIndex,
+    onSelect: (index) => {
+      const next = exercises[index];
+      if (next !== undefined) onSelect(next.id);
+    },
+  });
+
+  return (
+    <div className={joinClassNames('exercise-list', className)}>
+      {progressHeader ? (
+        <ExerciseProgressHeader
+          summary={progressSummary(
+            progress,
+            exercises.map((exercise) => exercise.id),
+          )}
+          onClearAll={onClearAll}
+          clearWarning={clearWarning}
+          clearDisabled={Object.keys(progress).length === 0}
+        />
+      ) : null}
+      <div
+        ref={listRef}
+        className="exercise-list__rows"
+        role="listbox"
+        aria-label={label ?? t('pedagogy.exercises')}
+        data-testid="exercise-list"
+      >
+        {exercises.map((exercise) => {
+          const record = progress[exercise.id];
+          const status = record?.status ?? 'idle';
+          const hints = record?.hintsRevealed ?? 0;
+          const active = exercise.id === activeId;
+          return (
+            <button
+              key={exercise.id}
+              type="button"
+              role="option"
+              aria-selected={active}
+              data-selected={active ? 'true' : undefined}
+              className={
+                active
+                  ? 'exercise-list__item exercise-list__item--active'
+                  : 'exercise-list__item'
+              }
+              onClick={() => {
+                onSelect(exercise.id);
+              }}
+            >
+              <ExerciseStatusIcon
+                status={status}
+                title={t(STATUS_TITLE[status])}
+              />
+              <span className="exercise-list__title">
+                {renderTitle === undefined ? (
+                  <InlineText text={exercise.title} />
+                ) : (
+                  renderTitle(exercise)
+                )}
+              </span>
+              <span className="exercise-list__tags">
+                {exercise.level === undefined ? null : (
+                  <ExerciseLevelTag level={exercise.level} active={active} />
+                )}
+                {tags?.(exercise)}
+                {status === 'solved' && hints > 0 ? (
+                  <Tag minimal round intent="success">
+                    {hints === 1
+                      ? t('pedagogy.solvedWithOneHint')
+                      : t('pedagogy.solvedWithHints', { count: hints })}
+                  </Tag>
+                ) : null}
+              </span>
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}