react-cheminfo 0.2.0 → 0.4.0

package/src/pedagogy/ui/SyntaxTooltip.tsx

@@ -0,0 +1,222 @@
+import type { Placement } from '@blueprintjs/core';
+import { Tooltip } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+/** The one worked example a documented construct carries. */
+export interface SyntaxTooltipExample {
+  /** The construct in use: a pattern, a SMILES, a LaTeX fragment, a layer. */
+  code: string;
+  /**
+   * What it is shown working on, for a construct whose example takes an input.
+   * @default undefined — the example is about notation only
+   */
+  input?: string;
+  /**
+   * What the example demonstrates, in one line.
+   * @default undefined
+   */
+  note?: string;
+}
+
+/** Everything the rich tooltip says about one construct. */
+export interface SyntaxTooltipContent {
+  /** The construct itself, shown in the highlighted chip. */
+  syntax: string;
+  /** Its name, in words: `Word boundary`, `Aromatic atom`, `Layer /c`. */
+  name: string;
+  /**
+   * Where it comes from, in small grey type: `RegExp.prototype.global`.
+   * @default undefined
+   */
+  tag?: string;
+  /** The one-line headline. */
+  summary: string;
+  /** The longer story, in a sentence or two. */
+  detail: string;
+  example: SyntaxTooltipExample;
+}
+
+export interface SyntaxTooltipProps {
+  /** What to explain. */
+  content: SyntaxTooltipContent;
+  /** What the student hovers: a cheatsheet row, a chip, a help icon. */
+  children: ReactNode;
+  /**
+   * Side the tooltip opens on. A cheatsheet row opens to its right, a chip in
+   * a toolbar below itself.
+   * @default 'bottom'
+   */
+  placement?: Placement;
+  /**
+   * Label of the example's code line.
+   * @default 'Example'
+   */
+  codeLabel?: string;
+  /**
+   * Label of the example's input line.
+   * @default 'Input'
+   */
+  inputLabel?: string;
+  /**
+   * Holds the tooltip open regardless of the pointer, for a page that pins one
+   * open on click and for showing the body on its own.
+   * @default undefined — the tooltip follows the pointer
+   */
+  isOpen?: boolean;
+}
+
+/**
+ * The one rich tooltip of a tool: cheatsheet rows, option chips and inline help
+ * icons all open this, so every documented construct is described at the same
+ * level of detail and adding a construct means adding the same five fields.
+ * @param props - The construct, and what opens it.
+ * @returns The hovered element, with its tooltip.
+ */
+export function SyntaxTooltip(props: SyntaxTooltipProps): ReactElement {
+  const {
+    content,
+    children,
+    placement = 'bottom',
+    codeLabel,
+    inputLabel,
+    isOpen,
+  } = props;
+
+  return (
+    <Tooltip
+      content={
+        <SyntaxTooltipBody
+          content={content}
+          codeLabel={codeLabel}
+          inputLabel={inputLabel}
+        />
+      }
+      hoverOpenDelay={HOVER_OPEN_DELAY}
+      placement={placement}
+      isOpen={isOpen}
+    >
+      {children}
+    </Tooltip>
+  );
+}
+
+export interface SyntaxTooltipBodyProps {
+  /** What to explain. */
+  content: SyntaxTooltipContent;
+  /**
+   * Label of the example's code line.
+   * @default 'Example'
+   */
+  codeLabel?: string;
+  /**
+   * Label of the example's input line.
+   * @default 'Input'
+   */
+  inputLabel?: string;
+}
+
+/**
+ * The body of the rich tooltip, on its own.
+ *
+ * A reference page that prints the same description under each construct shows
+ * this rather than restating the fields in a second layout.
+ * @param props - The construct, and how its example is labelled.
+ * @returns The body.
+ */
+export function SyntaxTooltipBody(props: SyntaxTooltipBodyProps): ReactElement {
+  const { content, codeLabel = 'Example', inputLabel = 'Input' } = props;
+  const { syntax, name, tag, summary, detail, example } = content;
+
+  return (
+    <div style={BODY_STYLE}>
+      <div style={HEADER_STYLE}>
+        <code style={SYNTAX_STYLE}>{syntax}</code>
+        <span style={NAME_STYLE}>{name}</span>
+        {tag !== undefined && <span style={TAG_STYLE}>{tag}</span>}
+      </div>
+      <div style={SUMMARY_STYLE}>{summary}</div>
+      <div style={DETAIL_STYLE}>{detail}</div>
+      <div style={EXAMPLE_STYLE}>
+        <div style={ROW_STYLE}>
+          <span style={LABEL_STYLE}>{codeLabel}</span>
+          <code style={VALUE_STYLE}>{example.code}</code>
+        </div>
+        {example.input !== undefined && (
+          <div style={ROW_STYLE}>
+            <span style={LABEL_STYLE}>{inputLabel}</span>
+            <code style={VALUE_STYLE}>{example.input}</code>
+          </div>
+        )}
+        {example.note !== undefined && (
+          <div style={NOTE_STYLE}>{example.note}</div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/** Long enough that the pointer can cross a row without opening it. */
+const HOVER_OPEN_DELAY = 150;
+
+const MONOSPACE = 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace';
+
+const BODY_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+  maxWidth: 360,
+};
+
+const HEADER_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'baseline',
+  flexWrap: 'wrap',
+  gap: 6,
+};
+
+const SYNTAX_STYLE: CSSProperties = {
+  background: 'rgb(255 255 255 / 15%)',
+  borderRadius: 3,
+  color: '#ffffff',
+  fontFamily: MONOSPACE,
+  fontSize: 14,
+  fontWeight: 600,
+  padding: '1px 6px',
+};
+
+const NAME_STYLE: CSSProperties = { fontWeight: 600, fontSize: 13 };
+
+const TAG_STYLE: CSSProperties = { color: '#abb3bf', fontSize: 11 };
+
+const SUMMARY_STYLE: CSSProperties = { fontSize: 12, lineHeight: 1.4 };
+
+const DETAIL_STYLE: CSSProperties = {
+  color: '#d3d8de',
+  fontSize: 12,
+  lineHeight: 1.45,
+};
+
+const EXAMPLE_STYLE: CSSProperties = {
+  borderTop: '1px solid rgb(255 255 255 / 15%)',
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 2,
+  paddingTop: 6,
+};
+
+const ROW_STYLE: CSSProperties = { display: 'flex', gap: 6, fontSize: 12 };
+
+const LABEL_STYLE: CSSProperties = { color: '#abb3bf', flex: '0 0 68px' };
+
+const VALUE_STYLE: CSSProperties = {
+  color: '#f6f7f9',
+  fontFamily: MONOSPACE,
+  overflowWrap: 'anywhere',
+};
+
+const NOTE_STYLE: CSSProperties = {
+  color: '#abb3bf',
+  fontSize: 12,
+  fontStyle: 'italic',
+  marginTop: 2,
+};

package/src/pedagogy/ui/TestCaseList.tsx

@@ -0,0 +1,122 @@
+import { Icon } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import type { TestCaseResult } from '../core/validation.ts';
+
+export interface TestCaseListProps<
+  TCase extends TestCaseResult = TestCaseResult,
+> {
+  /** The graded cases, in the order the validator returned them. */
+  results: readonly TCase[];
+  /**
+   * What names a case: the input it was run on, the atom it asked about. A
+   * tool that carries no such name lets the sentence speak for itself.
+   * @default undefined — the row shows only the reason
+   */
+  label?: (result: TCase, position: number) => ReactNode;
+  /**
+   * Whether the answer could not be graded at all — it does not compile, or
+   * there is nothing to mark yet. Every case is then drawn neutral rather than
+   * red, since none of them actually failed.
+   * @default false
+   */
+  pending?: boolean;
+  /**
+   * Class the list carries, so a site can reach it from its stylesheet.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * One row per graded case: whether it passes, and the sentence saying why not.
+ *
+ * The sentence is the validator's own — `match was "cat", expected "cats"` —
+ * and is never rewritten here: the explanation is the teaching, and a
+ * paraphrase would drop the value the student has to compare.
+ * @param props - The cases, and whether they could be graded at all.
+ * @returns The list, or nothing when there is no case to show.
+ */
+export function TestCaseList<TCase extends TestCaseResult>(
+  props: TestCaseListProps<TCase>,
+): ReactElement | null {
+  const { results, label, pending = false, className } = props;
+  if (results.length === 0) return null;
+
+  const rows: ReactNode[] = [];
+  for (let position = 0; position < results.length; position++) {
+    const result = results[position] as TCase;
+    rows.push(
+      <li key={`case-${position}`} style={itemStyle(result.passed, pending)}>
+        <Icon
+          icon={caseIcon(result.passed, pending)}
+          intent={caseIntent(result.passed, pending)}
+        />
+        <span>
+          {label !== undefined && (
+            <strong style={LABEL_STYLE}>{label(result, position)}</strong>
+          )}
+          {result.reason !== '' && (
+            <span style={REASON_STYLE}>{result.reason}</span>
+          )}
+        </span>
+      </li>,
+    );
+  }
+
+  return (
+    <ul className={className} style={LIST_STYLE}>
+      {rows}
+    </ul>
+  );
+}
+
+function caseIcon(
+  passed: boolean,
+  pending: boolean,
+): 'tick-circle' | 'circle' | 'cross-circle' {
+  if (passed) return 'tick-circle';
+  return pending ? 'circle' : 'cross-circle';
+}
+
+function caseIntent(
+  passed: boolean,
+  pending: boolean,
+): 'success' | 'danger' | 'none' {
+  if (passed) return 'success';
+  return pending ? 'none' : 'danger';
+}
+
+function itemStyle(passed: boolean, pending: boolean): CSSProperties {
+  const failed = !passed && !pending;
+  return {
+    display: 'flex',
+    alignItems: 'start',
+    gap: 8,
+    padding: '4px 8px',
+    borderRadius: 3,
+    borderLeft: `3px solid ${passed ? '#1c6e42' : failed ? '#cd4246' : '#c5cbd3'}`,
+    background: passed
+      ? 'rgb(236 253 245)'
+      : failed
+        ? 'rgb(254 243 242)'
+        : 'rgb(245 248 250)',
+  };
+}
+
+const LIST_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+  listStyle: 'none',
+  margin: 0,
+  padding: 0,
+};
+
+const LABEL_STYLE: CSSProperties = { marginRight: 6 };
+
+const REASON_STYLE: CSSProperties = {
+  display: 'block',
+  color: 'rgb(65 75 90)',
+  lineHeight: 1.4,
+};

package/src/pedagogy/ui/TutorialStepStrip.tsx

@@ -0,0 +1,230 @@
+import { Button, Tag, Tooltip } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import type { ExerciseLevel, TutorialStep } from '../core/types.ts';
+
+import { LEVEL_ORDER } from './exerciseMeta.ts';
+import type { TutorialLevelColours } from './tutorialLevels.ts';
+import { TUTORIAL_LEVEL_COLOURS } from './tutorialLevels.ts';
+
+export interface TutorialStepStripProps {
+  /** The whole tour, in teaching order. */
+  steps: readonly TutorialStep[];
+  /**
+   * Which step is open, as its position in `steps`. A position outside the
+   * tour is read as one of its ends, so a hand-edited link still opens.
+   */
+  activeIndex: number;
+  /** Called with the position of the step to open. */
+  onSelect: (index: number) => void;
+  /**
+   * What each strip is called — `Basics`, `π bonds, planarity, conjugation`.
+   * @default undefined — the level names its own strip
+   */
+  levelLabels?: Partial<Record<ExerciseLevel, string>>;
+  /**
+   * Whether Previous and Next sit under the strips. Both exist on purpose: the
+   * strips show the shape of the course and let a lecturer jump into it, the
+   * pager is how a student actually walks through it.
+   * @default true
+   */
+  pager?: boolean;
+  /**
+   * A word after the pager, for a tool whose steps also answer the keyboard.
+   * @default undefined
+   */
+  pagerHint?: ReactNode;
+  /**
+   * Class the strips carry, so a site can reach them from its stylesheet.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The numbered steps of the tour, one coloured strip per level, plus a pager.
+ * @param props - The tour, the open step, and how to move.
+ * @returns The strips and the pager.
+ */
+export function TutorialStepStrip(props: TutorialStepStripProps): ReactElement {
+  const {
+    steps,
+    activeIndex,
+    onSelect,
+    levelLabels,
+    pager = true,
+    pagerHint,
+    className,
+  } = props;
+  const active = clampIndex(activeIndex, steps.length);
+
+  return (
+    <div className={className} style={ROOT_STYLE}>
+      {LEVEL_ORDER.map((level) => {
+        const positions = positionsOfLevel(steps, level);
+        if (positions.length === 0) return null;
+        return (
+          <LevelStrip
+            key={level}
+            steps={steps}
+            positions={positions}
+            colours={TUTORIAL_LEVEL_COLOURS[level]}
+            label={levelLabels?.[level] ?? level}
+            activeIndex={active}
+            onSelect={onSelect}
+          />
+        );
+      })}
+
+      {pager && (
+        <div style={PAGER_STYLE}>
+          <Button
+            size="small"
+            icon="chevron-left"
+            text="Previous"
+            disabled={active === 0}
+            onClick={() => {
+              onSelect(active - 1);
+            }}
+          />
+          <Tag minimal round>
+            {`Step ${active + 1} of ${steps.length}`}
+          </Tag>
+          <Button
+            size="small"
+            endIcon="chevron-right"
+            text="Next"
+            intent="primary"
+            disabled={active >= steps.length - 1}
+            onClick={() => {
+              onSelect(active + 1);
+            }}
+          />
+          {pagerHint !== undefined && (
+            <span style={HINT_STYLE}>{pagerHint}</span>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+interface LevelStripProps {
+  steps: readonly TutorialStep[];
+  positions: readonly number[];
+  colours: TutorialLevelColours;
+  label: string;
+  activeIndex: number;
+  onSelect: (index: number) => void;
+}
+
+function LevelStrip(props: LevelStripProps): ReactElement {
+  const { steps, positions, colours, label, activeIndex, onSelect } = props;
+  const buttons: ReactNode[] = [];
+  for (const position of positions) {
+    const step = steps[position] as TutorialStep;
+    const active = position === activeIndex;
+    buttons.push(
+      <Tooltip
+        key={step.id}
+        content={step.title}
+        hoverOpenDelay={HOVER_OPEN_DELAY}
+        placement="bottom"
+      >
+        <button
+          type="button"
+          aria-label={`Step ${position + 1}: ${step.title}`}
+          aria-current={active ? 'step' : undefined}
+          style={numberStyle(colours, active)}
+          onClick={() => {
+            onSelect(position);
+          }}
+        >
+          {position + 1}
+        </button>
+      </Tooltip>,
+    );
+  }
+
+  return (
+    <div style={{ ...STRIP_STYLE, background: colours.background }}>
+      <span style={LABEL_STYLE}>{label}</span>
+      {buttons}
+    </div>
+  );
+}
+
+function positionsOfLevel(
+  steps: readonly TutorialStep[],
+  level: ExerciseLevel,
+): number[] {
+  const positions: number[] = [];
+  for (let index = 0; index < steps.length; index++) {
+    if (steps[index]?.level === level) positions.push(index);
+  }
+  return positions;
+}
+
+function clampIndex(index: number, total: number): number {
+  if (!Number.isFinite(index) || index <= 0) return 0;
+  return Math.min(Math.floor(index), Math.max(total - 1, 0));
+}
+
+/**
+ * The open step takes the darker shade of its own level, plus a border.
+ * @param colours - The two shades of the level the step belongs to.
+ * @param active - Whether this is the step on screen.
+ * @returns The style of one numbered button.
+ */
+function numberStyle(
+  colours: TutorialLevelColours,
+  active: boolean,
+): CSSProperties {
+  return {
+    background: active ? colours.activeBackground : '#ffffff',
+    border: active ? '2px solid #1c2127' : '1px solid rgb(17 20 24 / 20%)',
+    borderRadius: 4,
+    color: '#1c2127',
+    cursor: 'pointer',
+    font: 'inherit',
+    fontSize: 12,
+    fontWeight: active ? 700 : 500,
+    lineHeight: 1,
+    minWidth: 26,
+    padding: active ? '5px 6px' : '6px 7px',
+  };
+}
+
+/** Long enough that the pointer can cross the strip without opening a title. */
+const HOVER_OPEN_DELAY = 150;
+
+const ROOT_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+};
+
+const STRIP_STYLE: CSSProperties = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: 4,
+  borderRadius: 4,
+  padding: '4px 6px',
+};
+
+const LABEL_STYLE: CSSProperties = {
+  flex: '0 0 220px',
+  fontSize: 12,
+  fontWeight: 600,
+  color: '#1c2127',
+};
+
+const PAGER_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 8,
+  paddingTop: 2,
+};
+
+const HINT_STYLE: CSSProperties = { color: '#5b6875', fontSize: 11 };

package/src/pedagogy/ui/exerciseMeta.ts

@@ -0,0 +1,45 @@
+/**
+ * What a level and a status look like, in one place.
+ *
+ * A level means the same thing in the tutorial, in the exercise list and on the
+ * cheatsheet, so it is coloured from here rather than decided again per page.
+ */
+
+import type { IconName, Intent } from '@blueprintjs/core';
+
+import type { ExerciseLevel, ExerciseStatus } from '../core/types.ts';
+
+/** Green for a beginner, amber for an intermediate, red for an advanced one. */
+export const LEVEL_INTENT: Record<ExerciseLevel, Intent> = {
+  beginner: 'success',
+  intermediate: 'warning',
+  advanced: 'danger',
+};
+
+/** The three levels in teaching order, for a page listing all of them. */
+export const LEVEL_ORDER: readonly ExerciseLevel[] = [
+  'beginner',
+  'intermediate',
+  'advanced',
+];
+
+/** An empty circle, a warning sign, a tick: untouched, handed in, right. */
+export const STATUS_ICON: Record<ExerciseStatus, IconName> = {
+  idle: 'circle',
+  attempted: 'warning-sign',
+  solved: 'tick-circle',
+};
+
+/**
+ * Colour per status.
+ *
+ * `idle` is the one uncoloured value in the package: an exercise nobody has
+ * opened has nothing to report, and painting it would make a fresh list read as
+ * a list of mistakes. Every other value keeps its colour wherever it is shown,
+ * including on a tag that is switched off.
+ */
+export const STATUS_INTENT: Record<ExerciseStatus, Intent> = {
+  idle: 'none',
+  attempted: 'warning',
+  solved: 'success',
+};

package/src/pedagogy/ui/glossaryContext.ts

@@ -0,0 +1,23 @@
+/**
+ * Where the terms a site defines are kept while the page is open.
+ *
+ * Prose is rendered deep inside a card, a callout or a tooltip, and threading
+ * the glossary down to each of those as a prop is what makes a site stop
+ * linking its jargon. It is read from the surrounding provider instead.
+ */
+
+import { createContext, useContext } from 'react';
+
+import type { Glossary } from '../core/glossary.ts';
+
+/**
+ * The glossary the surrounding provider holds.
+ * @returns Every term the site defines, and no term at all when nothing wraps
+ * the tree — prose then renders its markers as plain words.
+ */
+export function useGlossary(): Glossary {
+  return useContext(GlossaryContext);
+}
+
+/** Holder of the glossary, written by `GlossaryProvider` and read by prose. */
+export const GlossaryContext = createContext<Glossary>({});

package/src/pedagogy/ui/index.ts

@@ -0,0 +1,37 @@
+export type { ExerciseActionsProps } from './ExerciseActions.tsx';
+export { ExerciseActions } from './ExerciseActions.tsx';
+export type { ExerciseProgressHeaderProps } from './ExerciseProgressHeader.tsx';
+export { ExerciseProgressHeader } from './ExerciseProgressHeader.tsx';
+export type {
+  ExerciseLevelTagProps,
+  ExerciseStatusIconProps,
+} from './ExerciseTags.tsx';
+export { ExerciseLevelTag, ExerciseStatusIcon } from './ExerciseTags.tsx';
+export { LEVEL_INTENT, LEVEL_ORDER, STATUS_ICON } from './exerciseMeta.ts';
+export type { GlossaryProviderProps } from './GlossaryProvider.tsx';
+export { GlossaryProvider } from './GlossaryProvider.tsx';
+export type { GlossaryTextProps } from './GlossaryText.tsx';
+export { GlossaryText } from './GlossaryText.tsx';
+export { useGlossary } from './glossaryContext.ts';
+export type { HintLadderProps } from './HintLadder.tsx';
+export { HintLadder } from './HintLadder.tsx';
+export type { ReferenceGridProps } from './ReferenceGrid.tsx';
+export { ReferenceGrid } from './ReferenceGrid.tsx';
+export type {
+  ReferenceRow,
+  ReferenceSection,
+  ReferenceSectionBlockProps,
+} from './ReferenceSectionBlock.tsx';
+export { ReferenceSectionBlock } from './ReferenceSectionBlock.tsx';
+export type {
+  SyntaxTooltipContent,
+  SyntaxTooltipExample,
+  SyntaxTooltipProps,
+} from './SyntaxTooltip.tsx';
+export { SyntaxTooltip } from './SyntaxTooltip.tsx';
+export type { TestCaseListProps } from './TestCaseList.tsx';
+export { TestCaseList } from './TestCaseList.tsx';
+export type { TutorialStepStripProps } from './TutorialStepStrip.tsx';
+export { TutorialStepStrip } from './TutorialStepStrip.tsx';
+export type { TutorialLevelColours } from './tutorialLevels.ts';
+export { TUTORIAL_LEVEL_COLOURS } from './tutorialLevels.ts';