react-cheminfo 0.3.0 → 0.4.0

package/src/pedagogy/core/glossary.ts

@@ -0,0 +1,122 @@
+/**
+ * The `[[term]]` marker language, parsed without a DOM.
+ *
+ * Authored prose — tutorial steps, exercise descriptions, hints — links its
+ * jargon by wrapping it in `[[double brackets]]`. A marker may be written
+ * `[[term|displayed text]]` when the sentence needs a different wording than
+ * the glossary key. Parsing and resolution live here, in plain TypeScript, so
+ * both are unit-tested without rendering anything.
+ */
+
+/** One worked example inside a glossary entry. */
+export interface GlossaryExample {
+  /** The construct itself: a pattern, a SMILES, a LaTeX fragment, a layer. */
+  code: string;
+  /**
+   * What the construct is shown working on, for a term whose examples take an
+   * input. Left out when the example is about notation only.
+   * @default undefined
+   */
+  input?: string;
+  /**
+   * What this example demonstrates, in one line.
+   * @default undefined
+   */
+  note?: string;
+}
+
+/** One glossary term, shown wherever a `[[marker]]` names it. */
+export interface GlossaryEntry {
+  /** The term, spelled out as the heading of the tooltip. */
+  title: string;
+  /** One short paragraph — the whole definition. */
+  summary: string;
+  /** Worked examples, shown under the summary. */
+  examples: GlossaryExample[];
+}
+
+/**
+ * Every term a site defines, keyed by the lowercased text inside a `[[...]]`.
+ *
+ * A key that no marker names is simply never shown, and a marker naming no key
+ * renders as plain prose — so the two sides may be written in either order.
+ */
+export type Glossary = Record<string, GlossaryEntry>;
+
+/**
+ * One piece of parsed prose: either a run of text, or one marker.
+ *
+ * `start` is the offset of the piece in the source string, which makes it a
+ * stable and unique React key — an array index is neither.
+ */
+export type GlossarySegment =
+  | { kind: 'text'; start: number; text: string }
+  | { kind: 'term'; start: number; term: string; text: string };
+
+/**
+ * Split authored prose into prose runs and markers.
+ *
+ * A marker yields the lowercased lookup `term` and the `text` to display, which
+ * are the same thing unless the marker used the `term|text` form. The term is
+ * never checked against any glossary here: an unknown term still produces a
+ * `term` segment, and the renderer falls back to showing its text as plain
+ * prose — an author may link a term months before it is written, and the page
+ * must never show the brackets. Text that never closes its brackets (`[[foo`)
+ * is not a marker at all and comes back verbatim inside a `text` segment.
+ * @param text - Authored prose, with or without markers.
+ * @returns The segments, in order, with no empty run between adjacent markers.
+ */
+export function parseGlossaryMarkers(text: string): GlossarySegment[] {
+  const segments: GlossarySegment[] = [];
+  // A fresh regexp per call: a /g/ literal carries `lastIndex` between calls.
+  const marker = new RegExp(MARKER_SOURCE, 'g');
+  let cursor = 0;
+  let match = marker.exec(text);
+  while (match !== null) {
+    if (match.index > cursor) {
+      segments.push({
+        kind: 'text',
+        start: cursor,
+        text: text.slice(cursor, match.index),
+      });
+    }
+    segments.push(toTermSegment(match.groups?.term ?? '', match.index));
+    cursor = match.index + match[0].length;
+    match = marker.exec(text);
+  }
+  if (cursor < text.length) {
+    segments.push({ kind: 'text', start: cursor, text: text.slice(cursor) });
+  }
+  return segments;
+}
+
+/**
+ * Resolve a marker term against a glossary, case-insensitively.
+ * @param glossary - The terms the site defines.
+ * @param term - The text before the pipe of a `[[marker]]`, in any case.
+ * @returns The entry, or `undefined` when no such term has been written yet.
+ */
+export function lookupGlossaryTerm(
+  glossary: Glossary,
+  term: string,
+): GlossaryEntry | undefined {
+  const key = term.trim().toLowerCase();
+  // `[[constructor]]` and `[[tostring]]` are prose, not inherited members.
+  return Object.hasOwn(glossary, key) ? glossary[key] : undefined;
+}
+
+const MARKER_SOURCE = String.raw`\[\[(?<term>[^\]]+)\]\]`;
+
+function toTermSegment(inner: string, start: number): GlossarySegment {
+  const pipe = inner.indexOf('|');
+  const rawTerm = pipe === -1 ? inner : inner.slice(0, pipe);
+  const rawText = pipe === -1 ? inner : inner.slice(pipe + 1);
+  const term = rawTerm.trim().toLowerCase();
+  const text = rawText.trim();
+  return {
+    kind: 'term',
+    start,
+    term,
+    text: text === '' ? rawTerm.trim() : text,
+  };
+}

package/src/pedagogy/core/index.ts

@@ -0,0 +1,28 @@
+export type {
+  Glossary,
+  GlossaryEntry,
+  GlossaryExample,
+  GlossarySegment,
+} from './glossary.ts';
+export { parseGlossaryMarkers } from './glossary.ts';
+export type {
+  ExerciseProgress,
+  LocalStorageProgressStoreOptions,
+  ProgressRecords,
+  ProgressStore,
+  ProgressSummary,
+} from './progress.ts';
+export { localStorageProgressStore, progressSummary } from './progress.ts';
+export type {
+  BaseExercise,
+  ExerciseLevel,
+  ExerciseSet,
+  ExerciseStatus,
+  TutorialStep,
+} from './types.ts';
+export type {
+  FinishValidationOptions,
+  TestCaseResult,
+  ValidationResult,
+} from './validation.ts';
+export { failedValidation, finishValidation } from './validation.ts';

package/src/pedagogy/core/jsonStorage.ts

@@ -0,0 +1,51 @@
+/**
+ * Best-effort JSON access to `localStorage`.
+ *
+ * A page framed in a course may have no storage at all — third-party storage is
+ * partitioned in Chrome and blocked in Safari — and a full quota must never
+ * take the page down with it. So both calls swallow everything: an unreadable
+ * entry reads as nothing stored, and a refused write is simply lost.
+ */
+
+/**
+ * Read one entry back as JSON.
+ * @param key - The storage key.
+ * @returns What was parsed, or `undefined` when there is nothing readable.
+ */
+export function readJsonEntry(key: string): unknown {
+  const storage = getStorage();
+  if (storage === null) return undefined;
+  try {
+    const raw = storage.getItem(key);
+    if (raw === null) return undefined;
+    return JSON.parse(raw) as unknown;
+  } catch {
+    // Corrupt JSON, or a store that refuses to be read.
+    return undefined;
+  }
+}
+
+/**
+ * Write one entry as JSON.
+ * @param key - The storage key.
+ * @param value - What to store.
+ */
+export function writeJsonEntry(key: string, value: unknown): void {
+  const storage = getStorage();
+  if (storage === null) return;
+  try {
+    storage.setItem(key, JSON.stringify(value));
+  } catch {
+    // Quota exceeded, or a store that refuses to be written.
+  }
+}
+
+function getStorage(): Storage | null {
+  try {
+    const candidate = globalThis.localStorage as Storage | undefined;
+    return candidate ?? null;
+  } catch {
+    // Reading localStorage throws outright when storage is blocked.
+    return null;
+  }
+}

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