react-cheminfo 0.64.1 → 0.65.0

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';

package/src/pedagogy/ui/seriesCounts.ts

@@ -0,0 +1,34 @@
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import type { Translate } from '../../i18n/core/translate.ts';
+
+/** The series lengths offered when a page names none. */
+export const SERIES_COUNTS: readonly number[] = [5, 10, 15, 20];
+
+/**
+ * The series lengths a pool can fill, and the whole pool last, so a pool
+ * smaller than the longest length is offered whole rather than overpromised.
+ * @param poolSize - How many questions the pool holds.
+ * @param counts - The lengths offered, or the family's when none.
+ * @param t - The chrome's formatter.
+ * @returns The options of the picker.
+ */
+export function seriesCountOptions(
+  poolSize: number,
+  counts: readonly number[] | undefined,
+  t: Translate<ChromeKey>,
+): Array<{ value: number; label: string }> {
+  const options: Array<{ value: number; label: string }> = [];
+  for (const count of counts ?? SERIES_COUNTS) {
+    if (count < poolSize) {
+      options.push({
+        value: count,
+        label: t('pedagogy.questionCount', { count }),
+      });
+    }
+  }
+  options.push({
+    value: poolSize,
+    label: t('pedagogy.allQuestions', { count: poolSize }),
+  });
+  return options;
+}

package/src/pedagogy/ui/seriesParts.tsx

@@ -0,0 +1,127 @@
+/**
+ * The two pieces of `ExerciseSeries` that are only layout: the heading row
+ * with the length picker and the new-series button, and the numbered list of
+ * questions.
+ */
+
+import { Button, HTMLSelect } from '@blueprintjs/core';
+import type { ReactElement, ReactNode, RefObject } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import type { Attempt } from '../core/attempts.ts';
+import type { ProgressRecords } from '../core/progress.ts';
+
+import { ExerciseStatusIcon } from './ExerciseTags.tsx';
+import { seriesCountOptions } from './seriesCounts.ts';
+
+/** What {@link SeriesHead} needs. */
+export interface SeriesHeadProps {
+  /** The heading, or the chrome's word for it. */
+  title: ReactNode | undefined;
+  /** Id of the heading. */
+  headingId: string;
+  /** The length on screen. */
+  count: number;
+  /** The largest length the tool serves. */
+  poolSize: number;
+  /** The lengths offered beside the whole pool. */
+  counts: readonly number[] | undefined;
+  /** Change the length. */
+  onCount: (count: number) => void;
+  /** Draw another series. */
+  onNewSeries: () => void;
+}
+
+/**
+ * The heading row of a series.
+ * @param props - See {@link SeriesHeadProps}.
+ * @returns The row.
+ */
+export function SeriesHead(props: SeriesHeadProps): ReactElement {
+  const { title, headingId, count, poolSize, counts, onCount, onNewSeries } =
+    props;
+  const t = useChromeT();
+  return (
+    <div className="exercise-series__head">
+      <h2 className="exercise-series__title" id={headingId}>
+        {title ?? t('pedagogy.questions')}
+      </h2>
+      <div className="exercise-series__controls">
+        <HTMLSelect
+          aria-label={t('pedagogy.questionsInSeries')}
+          value={count}
+          onChange={(event) => {
+            onCount(Number(event.currentTarget.value));
+          }}
+          options={seriesCountOptions(poolSize, counts, t)}
+        />
+        <Button
+          icon="refresh"
+          text={t('pedagogy.newSeries')}
+          title={t('pedagogy.newSeriesTitle')}
+          onClick={onNewSeries}
+        />
+      </div>
+    </div>
+  );
+}
+
+/** What {@link SeriesQuestionList} needs. */
+export interface SeriesQuestionListProps<Question> {
+  /** The questions of the series, in order. */
+  series: readonly Question[];
+  /** The attempt key of each, in the same order. */
+  keys: readonly string[];
+  /** Every attempt kept. */
+  records: ProgressRecords<Attempt>;
+  /** The open one. */
+  index: number;
+  /** Open one. */
+  onOpen: (index: number) => void;
+  /** How a question is named. */
+  label: (question: Question) => ReactNode;
+  /** The ref the arrow keys scroll inside. */
+  listRef: RefObject<HTMLElement | null>;
+}
+
+/**
+ * The numbered list of a series, each question with its status.
+ * @param props - See {@link SeriesQuestionListProps}.
+ * @returns The list.
+ */
+export function SeriesQuestionList<Question>(
+  props: SeriesQuestionListProps<Question>,
+): ReactElement {
+  const { series, keys, records, index, onOpen, label, listRef } = props;
+  const t = useChromeT();
+  return (
+    <nav
+      ref={listRef}
+      className="exercise-series__list"
+      aria-label={t('pedagogy.seriesQuestions')}
+    >
+      {series.map((entry, position) => {
+        const key = keys[position] ?? '';
+        return (
+          <Button
+            key={key}
+            variant="minimal"
+            alignText="start"
+            fill
+            active={position === index}
+            data-selected={position === index ? 'true' : undefined}
+            icon={
+              <ExerciseStatusIcon status={records[key]?.status ?? 'idle'} />
+            }
+            onClick={() => {
+              onOpen(position);
+            }}
+          >
+            <span className="exercise-series__number">{position + 1}.</span>{' '}
+            {label(entry)}
+          </Button>
+        );
+      })}
+    </nav>
+  );
+}

package/src/pedagogy/ui/useAttemptRecords.ts

@@ -0,0 +1,16 @@
+import { useSyncExternalStore } from 'react';
+
+import type { Attempt, AttemptStore } from '../core/attempts.ts';
+import type { ProgressRecords } from '../core/progress.ts';
+
+/**
+ * Every attempt a store holds, re-rendering the component whenever one
+ * changes.
+ * @param store - The site's attempt store.
+ * @returns The records, keyed by attempt key.
+ */
+export function useAttemptRecords(
+  store: AttemptStore,
+): ProgressRecords<Attempt> {
+  return useSyncExternalStore(store.subscribe, store.records, store.records);
+}

package/src/periodic/ui/PeriodicTable.tsx

@@ -77,10 +77,13 @@ export function PeriodicTable(props: PeriodicTableProps): ReactElement {
   // otherwise re-render all 118 cells per frame, and the engine recomputes
   // every length from the custom property on its own. A width of zero is a
   // table in a tab nobody has opened; the last measurement stands until it is
-  // shown, and the observer fires again then.
+  // shown, and the observer fires again then. `data-measured` says the cells
+  // now follow a measured width rather than the `1cqw` fallback.
   useResizeObserver(rootRef, ({ width }) => {
-    if (width === 0) return;
-    rootRef.current?.style.setProperty(UNIT_PROPERTY, unitValue(width));
+    const root = rootRef.current;
+    if (width === 0 || root === null) return;
+    root.style.setProperty(UNIT_PROPERTY, unitValue(width));
+    root.dataset.measured = '';
   });
 
   useEffect(() => {