react-cheminfo 0.2.0 → 0.4.0

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

package/src/pedagogy/ui/ReferenceSectionBlock.tsx

@@ -0,0 +1,175 @@
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { SyntaxTooltipContent } from './SyntaxTooltip.tsx';
+import { SyntaxTooltip } from './SyntaxTooltip.tsx';
+
+/** One line of the cheatsheet: a construct and what it does. */
+export interface ReferenceRow {
+  /** The construct itself, set in monospace. */
+  syntax: string;
+  /** What it does, in one line — short enough to read on paper. */
+  description: string;
+  /**
+   * The longer story, opened by hovering the row. A sparse section is meant to
+   * ship and be enriched later, so a row without one is plain text rather than
+   * a chip that opens nothing.
+   * @default undefined — the row is not interactive
+   */
+  tooltip?: SyntaxTooltipContent;
+}
+
+/** One titled block of the cheatsheet. */
+export interface ReferenceSection {
+  /** Stable and URL-safe: a heading can be linked to. */
+  id: string;
+  title: string;
+  /**
+   * One line under the heading, when the block needs framing.
+   * @default undefined
+   */
+  intro?: string;
+  /**
+   * Colour of the heading and of the rule under it, which is how the sections
+   * are told apart at a glance.
+   * @default undefined — the heading takes the surrounding text colour
+   */
+  color?: string;
+  rows: ReferenceRow[];
+  /**
+   * Whether the block is dropped from the printed sheet — a section that is
+   * only useful with a pointer, or one the site keeps for the screen.
+   * @default false
+   */
+  noPrint?: boolean;
+}
+
+export interface ReferenceSectionBlockProps {
+  section: ReferenceSection;
+  /**
+   * Width of the syntax column, so the blocks of one grid line up.
+   * @default 150
+   */
+  syntaxWidth?: number | string;
+  /**
+   * Class the block carries, in addition to `reference-section`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * A titled block of reference rows.
+ *
+ * The rows are spans in a flex column rather than a table: a tooltip target is
+ * wrapped in a `<span>`, which a browser hoists straight out of a `<tbody>`,
+ * and a table also breaks across pages far worse than a column does.
+ * @param props - The section, and how wide its syntax column is.
+ * @returns The block, kept whole across a page break.
+ */
+export function ReferenceSectionBlock(
+  props: ReferenceSectionBlockProps,
+): ReactElement {
+  const { section, syntaxWidth = 150, className } = props;
+
+  return (
+    <section
+      id={section.id}
+      className={blockClassName(section, className)}
+      style={SECTION_STYLE}
+    >
+      <h4 style={headingStyle(section.color)}>{section.title}</h4>
+      {section.intro !== undefined && (
+        <p style={INTRO_STYLE}>{section.intro}</p>
+      )}
+      {section.rows.map((row) => (
+        <ReferenceRowLine key={row.syntax} row={row} width={syntaxWidth} />
+      ))}
+    </section>
+  );
+}
+
+function ReferenceRowLine(props: {
+  row: ReferenceRow;
+  width: number | string;
+}): ReactElement {
+  const { row, width } = props;
+  const interactive = row.tooltip !== undefined;
+  const line = (
+    <span style={interactive ? INTERACTIVE_ROW_STYLE : ROW_STYLE}>
+      <span style={syntaxStyle(width, interactive)}>{row.syntax}</span>
+      <span style={DESCRIPTION_STYLE}>{row.description}</span>
+    </span>
+  );
+  if (row.tooltip === undefined) return line;
+  return (
+    <SyntaxTooltip content={row.tooltip} placement="right">
+      {line}
+    </SyntaxTooltip>
+  );
+}
+
+function blockClassName(
+  section: ReferenceSection,
+  className: string | undefined,
+): string {
+  const names = ['reference-section'];
+  if (section.noPrint === true) names.push('no-print');
+  if (className !== undefined) names.push(className);
+  return names.join(' ');
+}
+
+function headingStyle(color: string | undefined): CSSProperties {
+  return {
+    margin: '0 0 4px',
+    paddingBottom: 2,
+    fontSize: 13,
+    ...(color === undefined
+      ? {}
+      : { color, borderBottom: `2px solid ${color}` }),
+  };
+}
+
+function syntaxStyle(
+  width: number | string,
+  interactive: boolean,
+): CSSProperties {
+  return {
+    flex: `0 0 ${typeof width === 'number' ? `${width}px` : width}`,
+    fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+    fontSize: 12,
+    fontWeight: 600,
+    color: '#1c2127',
+    ...(interactive
+      ? { borderBottom: '1px dotted #5b6875', alignSelf: 'flex-start' }
+      : {}),
+  };
+}
+
+const SECTION_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  breakInside: 'avoid',
+};
+
+const INTRO_STYLE: CSSProperties = {
+  margin: '0 0 4px',
+  color: '#5b6875',
+  fontSize: 12,
+};
+
+const ROW_STYLE: CSSProperties = {
+  display: 'flex',
+  gap: 8,
+  padding: '3px 0',
+  borderTop: '1px solid #e5e7eb',
+  width: '100%',
+};
+
+const INTERACTIVE_ROW_STYLE: CSSProperties = { ...ROW_STYLE, cursor: 'help' };
+
+const DESCRIPTION_STYLE: CSSProperties = {
+  flex: '1 1 auto',
+  fontSize: 12,
+  lineHeight: 1.4,
+  color: '#404854',
+};