react-cheminfo 0.3.0 → 0.4.0

package/src/pedagogy/ui/ExerciseActions.tsx

@@ -0,0 +1,129 @@
+import { Button } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+export interface ExerciseActionsProps {
+  /**
+   * Records the attempt. Grading itself runs on every keystroke, so this
+   * button commits the verdict rather than producing it.
+   * @default undefined — no Check button
+   */
+  onCheck?: () => void;
+  /**
+   * Text of the Check button.
+   * @default 'Check'
+   */
+  checkLabel?: string;
+  /**
+   * Whether checking is impossible yet — nothing typed, nothing drawn.
+   * @default false
+   */
+  checkDisabled?: boolean;
+  /**
+   * Opens the next hint.
+   * @default undefined — no hint button; the ladder may carry its own
+   */
+  onRevealHint?: () => void;
+  /**
+   * How many hints are already open, for the button's count.
+   * @default 0
+   */
+  hintsRevealed?: number;
+  /**
+   * How many hints the exercise has, for the button's count.
+   * @default 0
+   */
+  hintCount?: number;
+  /**
+   * Shows or hides the sample answer. Never gated behind anything: getting
+   * stuck and reading the answer is part of how the intuition is built.
+   * @default undefined — no solution button
+   */
+  onToggleSolution?: () => void;
+  /**
+   * Whether the sample answer is on screen, which is what the button offers to
+   * undo.
+   * @default false
+   */
+  showSolution?: boolean;
+  /**
+   * Puts the exercise back to a blank answer, no hints and no solution.
+   * @default undefined — no Reset button
+   */
+  onReset?: () => void;
+  /**
+   * The buttons this tool adds — show the diagram, show the 3D view — rendered
+   * after the four standard ones.
+   * @default undefined
+   */
+  children?: ReactNode;
+  /**
+   * Class the row carries, so a site can reach it from its stylesheet.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The row of controls under an exercise: Check, Reveal hint, the solution, and
+ * Reset.
+ *
+ * Every one of them is optional, because a tool that grades live has no Check
+ * and a tool with a single-field answer has no Reset — what matters is that the
+ * ones a tool does offer read the same and sit in the same order everywhere.
+ * @param props - The actions the exercise offers.
+ * @returns The row.
+ */
+export function ExerciseActions(props: ExerciseActionsProps): ReactElement {
+  const {
+    onCheck,
+    checkLabel = 'Check',
+    checkDisabled = false,
+    onRevealHint,
+    hintsRevealed = 0,
+    hintCount = 0,
+    onToggleSolution,
+    showSolution = false,
+    onReset,
+    children,
+    className,
+  } = props;
+
+  return (
+    <div className={className} style={ROW_STYLE}>
+      {onCheck !== undefined && (
+        <Button
+          intent="primary"
+          icon="tick"
+          text={checkLabel}
+          disabled={checkDisabled}
+          onClick={onCheck}
+        />
+      )}
+      {onRevealHint !== undefined && (
+        <Button
+          icon="lightbulb"
+          text={`Reveal hint (${Math.min(hintsRevealed, hintCount)}/${hintCount})`}
+          disabled={hintsRevealed >= hintCount}
+          onClick={onRevealHint}
+        />
+      )}
+      {onToggleSolution !== undefined && (
+        <Button
+          icon={showSolution ? 'eye-off' : 'key'}
+          text={showSolution ? 'Hide solution' : 'Reveal solution'}
+          onClick={onToggleSolution}
+        />
+      )}
+      {onReset !== undefined && (
+        <Button icon="reset" text="Reset" onClick={onReset} />
+      )}
+      {children}
+    </div>
+  );
+}
+
+const ROW_STYLE: CSSProperties = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: 6,
+};

package/src/pedagogy/ui/ExerciseProgressHeader.tsx

@@ -0,0 +1,135 @@
+import { Alert, Button, ProgressBar } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import { useState } from 'react';
+
+import type { ProgressSummary } from '../core/progress.ts';
+
+export interface ExerciseProgressHeaderProps {
+  /** Where the student stands, as `progressSummary` counted it. */
+  summary: ProgressSummary;
+  /**
+   * Throws away every answer, every revealed hint and every solved exercise.
+   * Guarded by a dialog the student has to confirm.
+   * @default undefined — the header only reports, and offers no way to wipe
+   */
+  onClearAll?: () => void;
+  /**
+   * Text of the button that wipes the work.
+   * @default 'Clear all answers'
+   */
+  clearLabel?: string;
+  /**
+   * What the confirmation dialog says before the work is thrown away.
+   * @default a sentence saying what is lost and that there is no undo
+   */
+  clearWarning?: ReactNode;
+  /**
+   * Whether the button is dead — there is nothing stored to wipe.
+   * @default false
+   */
+  clearDisabled?: boolean;
+  /**
+   * Class the header carries, so a site can reach it from its stylesheet.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * How much of a set is solved, its bar, and the one way to wipe it.
+ *
+ * Wiping goes through a real dialog rather than `confirm()`: the button throws
+ * away a week of somebody's work, and a native prompt is both unstyled and
+ * dismissed by reflex.
+ * @param props - The counts, and what clearing does.
+ * @returns The header.
+ */
+export function ExerciseProgressHeader(
+  props: ExerciseProgressHeaderProps,
+): ReactElement {
+  const {
+    summary,
+    onClearAll,
+    clearLabel = 'Clear all answers',
+    clearWarning = DEFAULT_WARNING,
+    clearDisabled = false,
+    className,
+  } = props;
+  const [confirming, setConfirming] = useState(false);
+  const complete = summary.total > 0 && summary.solved === summary.total;
+
+  return (
+    <div className={className} style={ROOT_STYLE}>
+      <div style={ROW_STYLE}>
+        <span style={COUNT_STYLE}>
+          {`${summary.solved} / ${summary.total} solved`}
+        </span>
+        <span
+          style={PERCENT_STYLE}
+        >{`${Math.round(summary.ratio * 100)}%`}</span>
+        {onClearAll !== undefined && (
+          <Button
+            size="small"
+            variant="minimal"
+            intent="danger"
+            icon="trash"
+            text={clearLabel}
+            disabled={clearDisabled}
+            onClick={() => {
+              setConfirming(true);
+            }}
+          />
+        )}
+      </div>
+
+      <ProgressBar
+        animate={false}
+        stripes={false}
+        intent={complete ? 'success' : 'primary'}
+        value={summary.ratio}
+      />
+
+      {onClearAll !== undefined && (
+        <Alert
+          isOpen={confirming}
+          intent="danger"
+          icon="trash"
+          cancelButtonText="Keep my answers"
+          confirmButtonText="Clear everything"
+          onCancel={() => {
+            setConfirming(false);
+          }}
+          onConfirm={() => {
+            onClearAll();
+            setConfirming(false);
+          }}
+        >
+          {clearWarning}
+        </Alert>
+      )}
+    </div>
+  );
+}
+
+const DEFAULT_WARNING =
+  'This forgets every answer, every revealed hint and every solved exercise, on this browser. There is no undo.';
+
+const ROOT_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+};
+
+const ROW_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 8,
+};
+
+const COUNT_STYLE: CSSProperties = { fontWeight: 600 };
+
+const PERCENT_STYLE: CSSProperties = {
+  color: '#5b6875',
+  flex: '1 1 auto',
+  fontSize: 12,
+};

package/src/pedagogy/ui/ExerciseTags.tsx

@@ -0,0 +1,85 @@
+import { Icon, Tag } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import type { ExerciseLevel, ExerciseStatus } from '../core/types.ts';
+
+import { LEVEL_INTENT, STATUS_ICON, STATUS_INTENT } from './exerciseMeta.ts';
+
+export interface ExerciseLevelTagProps {
+  level: ExerciseLevel;
+  /**
+   * What the tag reads.
+   * @default the level itself — `beginner`, `intermediate`, `advanced`
+   */
+  label?: string;
+  /**
+   * Whether the tag is the one currently selected, which fills it in rather
+   * than leaving it minimal. Its colour does not depend on this: a level that
+   * is filtered out is still that level, and a tag that dropped to `none` when
+   * switched off would say the difficulty had changed.
+   * @default false
+   */
+  active?: boolean;
+  /**
+   * Called when the tag is clicked, which also makes it interactive.
+   * @default undefined — the tag only reports the level
+   */
+  onClick?: () => void;
+}
+
+/**
+ * The difficulty of an exercise or a step, as a coloured tag.
+ * @param props - The level, and whether it is the selected one.
+ * @returns The tag.
+ */
+export function ExerciseLevelTag(props: ExerciseLevelTagProps): ReactElement {
+  const { level, label = level, active = false, onClick } = props;
+
+  return (
+    <Tag
+      round
+      minimal={!active}
+      active={active}
+      intent={LEVEL_INTENT[level]}
+      interactive={onClick !== undefined}
+      onClick={onClick}
+    >
+      {label}
+    </Tag>
+  );
+}
+
+export interface ExerciseStatusIconProps {
+  status: ExerciseStatus;
+  /**
+   * What the pointer and a screen reader are told.
+   * @default the status itself — `idle`, `attempted`, `solved`
+   */
+  title?: string;
+  /**
+   * Size of the glyph, in pixels.
+   * @default undefined — Blueprint's standard 16
+   */
+  size?: number;
+}
+
+/**
+ * Where a student stands on one exercise, as the glyph in front of its title.
+ * @param props - The status, and how it is announced.
+ * @returns The icon.
+ */
+export function ExerciseStatusIcon(
+  props: ExerciseStatusIconProps,
+): ReactElement {
+  const { status, title = status, size } = props;
+
+  return (
+    <Icon
+      icon={STATUS_ICON[status]}
+      intent={STATUS_INTENT[status]}
+      size={size}
+      title={title}
+      aria-label={title}
+    />
+  );
+}

package/src/pedagogy/ui/GlossaryProvider.tsx

@@ -0,0 +1,31 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import type { Glossary } from '../core/glossary.ts';
+
+import { GlossaryContext } from './glossaryContext.ts';
+
+export interface GlossaryProviderProps {
+  /** Every term the site defines, keyed by the lowercased text of a marker. */
+  glossary: Glossary;
+  /** The part of the page whose prose resolves its markers against it. */
+  children: ReactNode;
+}
+
+/**
+ * Hand a glossary to every piece of prose below it.
+ *
+ * Wrap the whole tool once, high enough that a tutorial step, an exercise
+ * description and a revealed hint all sit under it: they are the three places
+ * jargon is linked, and they must define a term the same way.
+ * @param props - The terms, and the tree that uses them.
+ * @returns The tree, with the glossary in reach.
+ */
+export function GlossaryProvider(props: GlossaryProviderProps): ReactElement {
+  const { glossary, children } = props;
+
+  return (
+    <GlossaryContext.Provider value={glossary}>
+      {children}
+    </GlossaryContext.Provider>
+  );
+}

package/src/pedagogy/ui/GlossaryText.tsx

@@ -0,0 +1,164 @@
+import type { Placement } from '@blueprintjs/core';
+import { Tooltip } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import { Fragment } from 'react';
+
+import type { Glossary, GlossaryEntry } from '../core/glossary.ts';
+import { lookupGlossaryTerm, parseGlossaryMarkers } from '../core/glossary.ts';
+
+import { useGlossary } from './glossaryContext.ts';
+
+export interface GlossaryTextProps {
+  /**
+   * Authored prose. Every `[[term]]` — or `[[term|displayed text]]` — the
+   * glossary knows becomes a hoverable chip.
+   */
+  text: string;
+  /**
+   * Terms to resolve against, instead of the ones the surrounding provider
+   * holds. A page showing two vocabularies side by side passes its own here.
+   * @default undefined — the glossary of the surrounding `GlossaryProvider`
+   */
+  glossary?: Glossary;
+  /**
+   * Side the definition opens on.
+   * @default 'bottom'
+   */
+  placement?: Placement;
+  /**
+   * Class every chip carries, so a site can reach them from its stylesheet.
+   * @default 'glossary-term'
+   */
+  className?: string;
+}
+
+/**
+ * Render authored prose, turning its markers into hoverable definitions.
+ *
+ * A term the glossary has no entry for renders as its plain text, never as the
+ * brackets: prose is allowed to link a word months before anybody writes its
+ * definition, and the page must keep reading in the meantime.
+ * @param props - The prose, and where its terms are defined.
+ * @returns The prose, with the known terms made hoverable.
+ */
+export function GlossaryText(props: GlossaryTextProps): ReactElement {
+  const {
+    text,
+    glossary,
+    placement = 'bottom',
+    className = 'glossary-term',
+  } = props;
+  const fromProvider = useGlossary();
+  const terms = glossary ?? fromProvider;
+
+  const pieces: ReactNode[] = [];
+  for (const segment of parseGlossaryMarkers(text)) {
+    const entry =
+      segment.kind === 'term'
+        ? lookupGlossaryTerm(terms, segment.term)
+        : undefined;
+    if (entry === undefined) {
+      pieces.push(<Fragment key={segment.start}>{segment.text}</Fragment>);
+      continue;
+    }
+    pieces.push(
+      <Tooltip
+        key={segment.start}
+        content={<GlossaryTooltipBody entry={entry} />}
+        hoverOpenDelay={HOVER_OPEN_DELAY}
+        placement={placement}
+      >
+        <span className={className} style={TERM_STYLE}>
+          {segment.text}
+        </span>
+      </Tooltip>,
+    );
+  }
+
+  return <>{pieces}</>;
+}
+
+export interface GlossaryTooltipBodyProps {
+  /** The term to explain, already resolved from a marker. */
+  entry: GlossaryEntry;
+}
+
+/**
+ * The definition itself: the term, one paragraph, then the worked examples.
+ *
+ * Exported on its own so a glossary page can list every term with the body it
+ * shows on hover, rather than describing the same entry twice.
+ * @param props - The entry to show.
+ * @returns The body of the tooltip.
+ */
+export function GlossaryTooltipBody(
+  props: GlossaryTooltipBodyProps,
+): ReactElement {
+  const { entry } = props;
+
+  return (
+    <div style={BODY_STYLE}>
+      <div style={TITLE_STYLE}>{entry.title}</div>
+      <div style={SUMMARY_STYLE}>{entry.summary}</div>
+      {entry.examples.length > 0 && (
+        <ul style={LIST_STYLE}>
+          {entry.examples.map((example) => (
+            <li key={`${example.code}::${example.input ?? ''}`}>
+              <code style={CODE_STYLE}>{example.code}</code>
+              {example.input !== undefined && (
+                <span style={INPUT_STYLE}>{` on ${example.input}`}</span>
+              )}
+              {example.note !== undefined && (
+                <div style={NOTE_STYLE}>{example.note}</div>
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+/** Long enough that the pointer can cross a chip without opening it. */
+const HOVER_OPEN_DELAY = 150;
+
+const TERM_STYLE: CSSProperties = {
+  borderBottom: '1px dotted currentColor',
+  color: 'var(--accent, inherit)',
+  cursor: 'help',
+};
+
+const BODY_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+  maxWidth: 340,
+};
+
+const TITLE_STYLE: CSSProperties = { fontWeight: 600, fontSize: 13 };
+
+const SUMMARY_STYLE: CSSProperties = {
+  fontSize: 12,
+  lineHeight: 1.45,
+  color: '#d3d8de',
+};
+
+const LIST_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+  margin: 0,
+  paddingLeft: 16,
+  fontSize: 12,
+  lineHeight: 1.4,
+};
+
+const CODE_STYLE: CSSProperties = {
+  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+  fontWeight: 600,
+  color: '#8abbff',
+};
+
+const INPUT_STYLE: CSSProperties = { color: '#f6f7f9' };
+
+const NOTE_STYLE: CSSProperties = { fontStyle: 'italic', color: '#abb3bf' };

package/src/pedagogy/ui/HintLadder.tsx

@@ -0,0 +1,95 @@
+import { Button, Callout } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import { GlossaryText } from './GlossaryText.tsx';
+
+export interface HintLadderProps {
+  /** Every hint of the exercise, ordered from a nudge to almost the answer. */
+  hints: readonly string[];
+  /**
+   * How many the student has asked for. A count outside the ladder is read as
+   * one of its ends, so a stored value from a shorter or longer ladder still
+   * opens the page.
+   */
+  revealed: number;
+  /**
+   * Opens the next hint. Leave it out where the button lives elsewhere — in
+   * `ExerciseActions`, say — and the ladder only shows what is already open.
+   * @default undefined — no button
+   */
+  onReveal?: () => void;
+  /**
+   * Text of the button, before its count.
+   * @default 'Reveal hint'
+   */
+  revealLabel?: string;
+  /**
+   * Heading over the hints.
+   * @default 'Hints'
+   */
+  title?: string;
+}
+
+/**
+ * The hints asked for so far, and the button that opens the next one.
+ *
+ * One at a time, in order: a ladder that dumped all four at once is a solution
+ * with extra steps. The prose goes through the glossary, so a hint may link its
+ * jargon exactly like the statement above it.
+ * @param props - The ladder, how much of it is open, and how to open more.
+ * @returns The hints, or nothing while none is open and none can be.
+ */
+export function HintLadder(props: HintLadderProps): ReactElement | null {
+  const {
+    hints,
+    revealed,
+    onReveal,
+    revealLabel = 'Reveal hint',
+    title = 'Hints',
+  } = props;
+  const open = clampRevealed(revealed, hints.length);
+  const exhausted = open >= hints.length;
+  if (open === 0 && (onReveal === undefined || hints.length === 0)) return null;
+
+  return (
+    <div style={ROOT_STYLE}>
+      {onReveal !== undefined && hints.length > 0 && (
+        <div>
+          <Button
+            icon="lightbulb"
+            text={`${revealLabel} (${open}/${hints.length})`}
+            disabled={exhausted}
+            onClick={onReveal}
+          />
+        </div>
+      )}
+
+      {open > 0 && (
+        <Callout intent="primary" icon="lightbulb" title={title}>
+          <ol style={LIST_STYLE}>
+            {hints.slice(0, open).map((hint) => (
+              <li key={hint} style={ITEM_STYLE}>
+                <GlossaryText text={hint} />
+              </li>
+            ))}
+          </ol>
+        </Callout>
+      )}
+    </div>
+  );
+}
+
+function clampRevealed(revealed: number, total: number): number {
+  if (!Number.isFinite(revealed) || revealed <= 0) return 0;
+  return Math.min(Math.floor(revealed), total);
+}
+
+const ROOT_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 8,
+};
+
+const LIST_STYLE: CSSProperties = { margin: 0, paddingLeft: 18 };
+
+const ITEM_STYLE: CSSProperties = { lineHeight: 1.45 };

package/src/pedagogy/ui/ReferenceGrid.tsx

@@ -0,0 +1,69 @@
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { ReferenceSection } from './ReferenceSectionBlock.tsx';
+import { ReferenceSectionBlock } from './ReferenceSectionBlock.tsx';
+
+export interface ReferenceGridProps {
+  /** The blocks of the cheatsheet, in reading order. */
+  sections: readonly ReferenceSection[];
+  /**
+   * Width under which a column wraps to the next line, in pixels.
+   * @default 320
+   */
+  minColumnWidth?: number;
+  /**
+   * Width of the syntax column of every block, so they line up across columns.
+   * @default 150
+   */
+  syntaxWidth?: number | string;
+  /**
+   * Class the grid carries, in addition to `reference-grid`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The whole cheatsheet: as many columns as the paper or the window allows.
+ *
+ * Students print this page and take it into an exam room, so the columns
+ * reflow to the sheet and every block is kept off a page break.
+ * @param props - The sections, and how they are laid out.
+ * @returns The grid.
+ */
+export function ReferenceGrid(props: ReferenceGridProps): ReactElement {
+  const {
+    sections,
+    minColumnWidth = 320,
+    syntaxWidth = 150,
+    className,
+  } = props;
+
+  return (
+    <div
+      className={
+        className === undefined
+          ? 'reference-grid'
+          : `reference-grid ${className}`
+      }
+      style={gridStyle(minColumnWidth)}
+    >
+      {sections.map((section) => (
+        <ReferenceSectionBlock
+          key={section.id}
+          section={section}
+          syntaxWidth={syntaxWidth}
+        />
+      ))}
+    </div>
+  );
+}
+
+function gridStyle(minColumnWidth: number): CSSProperties {
+  return {
+    display: 'grid',
+    gridTemplateColumns: `repeat(auto-fit, minmax(${minColumnWidth}px, 1fr))`,
+    gap: '10px 24px',
+    alignItems: 'start',
+  };
+}