react-cheminfo 0.3.0 → 0.4.0

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

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