react-cheminfo 0.64.0 → 0.65.0

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

package/src/pedagogy/ui/ExerciseSeries.tsx

@@ -0,0 +1,250 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useEffect, useEffectEvent, useMemo, useState } from 'react';
+
+import { useDocumentListNavigation } from '../../hooks/ui/useDocumentListNavigation.ts';
+import type { SplitRange } from '../../split/core/split.ts';
+import { clampSplit } from '../../split/core/split.ts';
+import { SplitRow } from '../../split/ui/SplitRow.tsx';
+import type { AttemptStore } from '../core/attempts.ts';
+import { attemptKey } from '../core/attempts.ts';
+import { progressSummary } from '../core/progress.ts';
+import type { PickSeededOptions, SeedRange } from '../core/seed.ts';
+import { freshSeed, pickSeeded } from '../core/seed.ts';
+import type { SeriesTool } from '../core/series.ts';
+
+import { ExerciseProgressHeader } from './ExerciseProgressHeader.tsx';
+import type { QuestionRendering } from './QuestionCard.tsx';
+import { QuestionCard } from './QuestionCard.tsx';
+import { SeriesHead, SeriesQuestionList } from './seriesParts.tsx';
+import { useAttemptRecords } from './useAttemptRecords.ts';
+
+/** What {@link ExerciseSeries} needs. */
+export interface ExerciseSeriesProps<
+  Question,
+> extends QuestionRendering<Question> {
+  /** The tool the series is drawn from. */
+  tool: SeriesTool<Question>;
+  /** Where the attempts, and the series each tool was last on, are kept. */
+  store: AttemptStore;
+  /** How a question is named in the list beside the card. */
+  label: (question: Question) => ReactNode;
+  /**
+   * The seed the address names, read with `parseSeed`, or `null` when it names
+   * none — the series this browser was last on is then written into it.
+   */
+  seed: number | null;
+  /**
+   * Write a seed into the address: `replace` when the page adopts one it was
+   * opened without, `push` when the student draws a new series, so Back
+   * returns to the previous one.
+   */
+  onSeed: (seed: number, history: 'replace' | 'push') => void;
+  /** How many questions the student asked for; the pool caps it. */
+  count: number;
+  /** Change how many questions the series holds. */
+  onCount: (count: number) => void;
+  /**
+   * The lengths offered, beside the whole pool.
+   * @default [5, 10, 15, 20]
+   */
+  counts?: readonly number[];
+  /**
+   * The share of the row the list takes, as the address names it, or `null`
+   * for {@link ExerciseSeriesProps.defaultSplit}.
+   */
+  split: number | null;
+  /** Write the share a drag came to rest at, or `null` for the default. */
+  onSplit: (split: number | null) => void;
+  /**
+   * The share the list opens at: the card is the figure, so the list opens
+   * narrow.
+   * @default 22
+   */
+  defaultSplit?: number;
+  /**
+   * How far the list may be dragged, measured on the labels of the pool.
+   * @default { min: 15, max: 26 }
+   */
+  splitRange?: SplitRange;
+  /**
+   * The narrowest row still divided, in pixels; under it the list stacks under
+   * the card's row, as on a tablet held upright.
+   * @default SplitRow's own, 860
+   */
+  stackBelow?: number;
+  /**
+   * How the series is drawn from the pool, for a site whose links were written
+   * with the other generator call.
+   * @default { draw: 'getFloat', wrap: false }
+   */
+  pick?: PickSeededOptions;
+  /**
+   * The seeds a new series is drawn from.
+   * @default every unsigned 32-bit integer
+   */
+  seedRange?: SeedRange;
+  /**
+   * The heading over the series.
+   * @default the chrome's own word for it, in the language of the page
+   */
+  title?: ReactNode;
+  /**
+   * Id of the heading, for a section labelled by it.
+   * @default 'questions-heading'
+   */
+  headingId?: string;
+}
+
+const DEFAULT_RANGE: SplitRange = { min: 15, max: 26 };
+
+/**
+ * A graded series drawn from a tool's pool: the list of its questions, the one
+ * open, and the progress over the series.
+ *
+ * The series is its seed, and the seed is in the address, so the link on
+ * screen reopens the same questions for anyone — a teacher hands one series to
+ * a whole class. How the row is divided between the list and the open question
+ * travels in the address too. The component reads neither: the page hands it
+ * the seed, the length and the share, and is told when one changes.
+ * @param props - The tool, where its attempts are kept, the address values,
+ * and how to draw a question.
+ * @returns The series.
+ */
+export function ExerciseSeries<Question>(
+  props: ExerciseSeriesProps<Question>,
+): ReactElement {
+  const {
+    tool,
+    store,
+    label,
+    seed: addressSeed,
+    onSeed,
+    count: wanted,
+    onCount,
+    counts,
+    split,
+    onSplit,
+    defaultSplit = 22,
+    splitRange = DEFAULT_RANGE,
+    stackBelow,
+    pick,
+    seedRange,
+    title,
+    headingId = 'questions-heading',
+    ...rendering
+  } = props;
+  const records = useAttemptRecords(store);
+  const [fallbackSeed] = useState(
+    () => store.storedSeed(tool.id) ?? freshSeed(seedRange),
+  );
+  const seed = addressSeed ?? fallbackSeed;
+  const poolSize = tool.maxCount ?? tool.pool.length;
+  const count = Math.min(wanted, poolSize);
+
+  // The address is what the series is read from and handed out as, so a page
+  // opened without a seed writes the one it fell back on into it; and the
+  // series on screen is the one this tool reopens on the next visit.
+  const followSeed = useEffectEvent((): void => {
+    if (addressSeed === null) onSeed(fallbackSeed, 'replace');
+    store.storeSeed(tool.id, addressSeed ?? fallbackSeed);
+  });
+  useEffect(() => {
+    followSeed();
+  }, [seed, addressSeed, tool.id]);
+
+  const series = useMemo(
+    () =>
+      tool.draw === undefined
+        ? pickSeeded(tool.pool, count, seed, pick)
+        : tool.draw(count, seed),
+    [tool, count, seed, pick],
+  );
+  const keys = useMemo(
+    () =>
+      series.map((question) => attemptKey(tool.id, seed, tool.key(question))),
+    [series, tool, seed],
+  );
+
+  const [opened, setOpened] = useState({ seed, index: 0 });
+  const index =
+    opened.seed === seed ? Math.min(opened.index, series.length - 1) : 0;
+  function open(next: number): void {
+    setOpened({ seed, index: next });
+  }
+  const listRef = useDocumentListNavigation<HTMLElement>({
+    length: series.length,
+    selectedIndex: index,
+    onSelect: open,
+  });
+
+  const summary = progressSummary(records, keys);
+  const question = series[index];
+  const storageKey = keys[index];
+
+  return (
+    <div className="exercise-series">
+      <SeriesHead
+        title={title}
+        headingId={headingId}
+        count={count}
+        poolSize={poolSize}
+        counts={counts}
+        onCount={onCount}
+        onNewSeries={() => {
+          const next = freshSeed(seedRange);
+          store.forgetOtherSeries(tool.id, next);
+          onSeed(next, 'push');
+        }}
+      />
+
+      <ExerciseProgressHeader
+        summary={summary}
+        onClearAll={() => {
+          store.clearAttempts(keys);
+        }}
+        clearDisabled={!keys.some((key) => records[key] !== undefined)}
+      />
+
+      <SplitRow
+        ratio={split === null ? null : clampSplit(split, splitRange)}
+        defaultRatio={defaultSplit}
+        min={splitRange.min}
+        max={splitRange.max}
+        stackBelow={stackBelow}
+        onRatio={onSplit}
+        start={
+          <SeriesQuestionList
+            series={series}
+            keys={keys}
+            records={records}
+            index={index}
+            onOpen={open}
+            label={label}
+            listRef={listRef}
+          />
+        }
+        end={
+          question === undefined || storageKey === undefined ? null : (
+            <QuestionCard
+              key={storageKey}
+              tool={tool}
+              question={question}
+              store={store}
+              storageKey={storageKey}
+              number={index + 1}
+              total={series.length}
+              onNext={
+                index + 1 < series.length
+                  ? () => {
+                      open(index + 1);
+                    }
+                  : undefined
+              }
+              {...rendering}
+            />
+          )
+        }
+      />
+    </div>
+  );
+}

package/src/pedagogy/ui/QuestionCard.tsx

@@ -0,0 +1,231 @@
+import { Button, Callout, Tag } from '@blueprintjs/core';
+import type { ReactElement, ReactNode } from 'react';
+import { useMemo } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { useIsHidden } from '../../share/ui/hiddenParts.ts';
+import type { AttemptStore } from '../core/attempts.ts';
+import { emptyAttempt } from '../core/attempts.ts';
+import type { Answers, FieldCase, SeriesTool } from '../core/series.ts';
+
+import { AnswerFields } from './AnswerFields.tsx';
+import { ExerciseActions } from './ExerciseActions.tsx';
+import { GlossaryText } from './GlossaryText.tsx';
+import { HintLadder } from './HintLadder.tsx';
+import { TestCaseList } from './TestCaseList.tsx';
+import { LEVEL_INTENT } from './exerciseMeta.ts';
+import { useAttemptRecords } from './useAttemptRecords.ts';
+
+/** What a tool's own answer input is handed. */
+export interface AnswerInputProps<Question> {
+  /** The question being answered. */
+  question: Question;
+  /** What is typed so far, field by field. */
+  answers: Answers;
+  /** Change one field. */
+  onChange: (key: string, value: string) => void;
+  /** Check the answer, as Enter does in a box. */
+  onSubmit: () => void;
+}
+
+/** How one tool draws the parts of a question the card does not know. */
+export interface QuestionRendering<Question> {
+  /** The statement of the question. */
+  prompt: (question: Question) => ReactNode;
+  /**
+   * An input of the tool's own — a drawing canvas, a reaction to balance — in
+   * place of the typed boxes.
+   * @default undefined — one box per field of the tool
+   */
+  answer?: (props: AnswerInputProps<Question>) => ReactNode;
+  /**
+   * What the solution shows beyond its text, such as a drawn structure.
+   * @default undefined
+   */
+  solution?: (question: Question) => ReactNode;
+}
+
+/** What {@link QuestionCard} needs. */
+export interface QuestionCardProps<
+  Question,
+> extends QuestionRendering<Question> {
+  /** The tool the question belongs to. */
+  tool: SeriesTool<Question>;
+  /** The question on the card. */
+  question: Question;
+  /** Where the attempts are kept. */
+  store: AttemptStore;
+  /** The key this question's attempt is kept under, from `attemptKey`. */
+  storageKey: string;
+  /** Its position in the series, counted from 1. */
+  number: number;
+  /** How many questions the series holds. */
+  total: number;
+  /**
+   * Open the next question; left out on the last one.
+   * @default undefined
+   */
+  onNext?: () => void;
+}
+
+/**
+ * One question: its statement, the answer, the four actions, and — once
+ * checked — the verdict case by case, the hints taken and the solution.
+ *
+ * The answer is graded on every change, but the verdict is shown only for the
+ * answer as it was checked: a numeric answer that turned green as it was typed
+ * could be found by trying numbers. A link that hides the `solutions` part
+ * takes the solution button away.
+ * @param props - The tool, the question, where its attempt is kept, and how to
+ * draw it.
+ * @returns The card.
+ */
+export function QuestionCard<Question>(
+  props: QuestionCardProps<Question>,
+): ReactElement {
+  const {
+    tool,
+    question,
+    store,
+    storageKey,
+    number,
+    total,
+    onNext,
+    prompt,
+    answer,
+    solution,
+  } = props;
+  const t = useChromeT();
+  const isHidden = useIsHidden();
+  const records = useAttemptRecords(store);
+  const {
+    answers,
+    checked: checkedAnswers,
+    hintsRevealed,
+    showSolution,
+  } = records[storageKey] ?? emptyAttempt();
+  const check = useMemo(
+    () => tool.grade(question, answers),
+    [tool, question, answers],
+  );
+  const hints = useMemo(() => tool.hints(question), [tool, question]);
+  const snapshot = JSON.stringify(answers);
+  const checked = checkedAnswers === snapshot;
+  const solutionsHidden = isHidden('solutions');
+  const level = tool.level?.(question);
+
+  function setAnswer(key: string, value: string): void {
+    store.updateAttempt(storageKey, { answers: { ...answers, [key]: value } });
+  }
+
+  function commit(): void {
+    store.updateAttempt(storageKey, {
+      status: check.passed ? 'solved' : 'attempted',
+      checked: snapshot,
+    });
+  }
+
+  return (
+    <article
+      className="series-question"
+      aria-label={t('pedagogy.questionNumber', { number })}
+    >
+      <div className="series-question__meta">
+        <span>{t('pedagogy.questionOf', { number, total })}</span>
+        {level === undefined ? null : (
+          <Tag minimal intent={LEVEL_INTENT[level]}>
+            {level}
+          </Tag>
+        )}
+      </div>
+      <div className="series-question__prompt">{prompt(question)}</div>
+
+      {answer ? (
+        answer({ question, answers, onChange: setAnswer, onSubmit: commit })
+      ) : (
+        <AnswerFields
+          fields={tool.fields(question)}
+          answers={answers}
+          onChange={setAnswer}
+          onSubmit={commit}
+        />
+      )}
+
+      <ExerciseActions
+        onCheck={commit}
+        checkDisabled={isBlank(answers)}
+        onRevealHint={() => {
+          store.updateAttempt(storageKey, {
+            hintsRevealed: Math.min(hintsRevealed + 1, hints.length),
+          });
+        }}
+        hintsRevealed={hintsRevealed}
+        hintCount={hints.length}
+        onToggleSolution={
+          solutionsHidden
+            ? undefined
+            : () => {
+                store.updateAttempt(storageKey, {
+                  showSolution: !showSolution,
+                });
+              }
+        }
+        showSolution={showSolution}
+        onReset={() => {
+          store.updateAttempt(storageKey, emptyAttempt());
+        }}
+      />
+
+      {checked ? (
+        <TestCaseList<FieldCase>
+          results={check.cases}
+          label={(verdict) => verdict.label}
+        />
+      ) : null}
+
+      {checked && check.passed ? (
+        <Callout
+          intent="success"
+          icon="tick-circle"
+          title={t('pedagogy.solved')}
+        >
+          {hintsRevealed > 0
+            ? t('pedagogy.solvedWithHintsOf', {
+                revealed: hintsRevealed,
+                total: hints.length,
+              })
+            : t('pedagogy.solvedWithoutHint')}
+          {onNext ? (
+            <Button
+              className="series-question__next"
+              intent="success"
+              endIcon="arrow-right"
+              text={t('pedagogy.nextQuestion')}
+              onClick={onNext}
+            />
+          ) : null}
+        </Callout>
+      ) : null}
+
+      {hintsRevealed > 0 ? (
+        <HintLadder hints={hints} revealed={hintsRevealed} />
+      ) : null}
+
+      {showSolution && !solutionsHidden ? (
+        <Callout intent="warning" icon="key" title={t('pedagogy.solution')}>
+          <p className="series-question__solution">
+            <GlossaryText text={tool.solution(question)} />
+          </p>
+          {solution?.(question)}
+        </Callout>
+      ) : null}
+    </article>
+  );
+}
+
+function isBlank(answers: Answers): boolean {
+  for (const value of Object.values(answers)) {
+    if (value.trim() !== '') return false;
+  }
+  return true;
+}

package/src/pedagogy/ui/index.ts

@@ -51,3 +51,21 @@ export type {
 export { TutorialStepStrip } from './TutorialStepStrip.tsx';
 export type { TutorialLevelColours } from './tutorialLevels.ts';
 export { TUTORIAL_LEVEL_COLOURS } from './tutorialLevels.ts';
+export type { AnswerFieldsProps } from './AnswerFields.tsx';
+export { AnswerFields } from './AnswerFields.tsx';
+export type {
+  ExerciseListEntry,
+  ExerciseListProgress,
+  ExerciseListProps,
+} from './ExerciseList.tsx';
+export { ExerciseList } from './ExerciseList.tsx';
+export type { ExerciseSeriesProps } from './ExerciseSeries.tsx';
+export { ExerciseSeries } from './ExerciseSeries.tsx';
+export type {
+  AnswerInputProps,
+  QuestionCardProps,
+  QuestionRendering,
+} from './QuestionCard.tsx';
+export { QuestionCard } from './QuestionCard.tsx';
+export { SERIES_COUNTS } from './seriesCounts.ts';
+export { useAttemptRecords } from './useAttemptRecords.ts';