react-cheminfo 0.10.0 → 0.12.0

package/src/pedagogy/ui/ExerciseTags.tsx

@@ -5,7 +5,9 @@ import type { ExerciseLevel, ExerciseStatus } from '../core/types.ts';
 
 import { LEVEL_INTENT, STATUS_ICON, STATUS_INTENT } from './exerciseMeta.ts';
 
+/** What {@link ExerciseLevelTag} needs. */
 export interface ExerciseLevelTagProps {
+  /** The difficulty the tag shows, which also picks its colour. */
   level: ExerciseLevel;
   /**
    * What the tag reads.
@@ -25,6 +27,11 @@ export interface ExerciseLevelTagProps {
    * @default undefined — the tag only reports the level
    */
   onClick?: () => void;
+  /**
+   * Class names added to the root element, after the component's own.
+   * @default undefined
+   */
+  className?: string;
 }
 
 /**
@@ -33,10 +40,11 @@ export interface ExerciseLevelTagProps {
  * @returns The tag.
  */
 export function ExerciseLevelTag(props: ExerciseLevelTagProps): ReactElement {
-  const { level, label = level, active = false, onClick } = props;
+  const { className, level, label = level, active = false, onClick } = props;
 
   return (
     <Tag
+      className={className}
       round
       minimal={!active}
       active={active}
@@ -49,7 +57,9 @@ export function ExerciseLevelTag(props: ExerciseLevelTagProps): ReactElement {
   );
 }
 
+/** What {@link ExerciseStatusIcon} needs. */
 export interface ExerciseStatusIconProps {
+  /** Where the student stands on the exercise, which picks the glyph. */
   status: ExerciseStatus;
   /**
    * What the pointer and a screen reader are told.
@@ -61,6 +71,11 @@ export interface ExerciseStatusIconProps {
    * @default undefined — Blueprint's standard 16
    */
   size?: number;
+  /**
+   * Class names added to the root element, after the component's own.
+   * @default undefined
+   */
+  className?: string;
 }
 
 /**
@@ -71,10 +86,11 @@ export interface ExerciseStatusIconProps {
 export function ExerciseStatusIcon(
   props: ExerciseStatusIconProps,
 ): ReactElement {
-  const { status, title = status, size } = props;
+  const { className, status, title = status, size } = props;
 
   return (
     <Icon
+      className={className}
       icon={STATUS_ICON[status]}
       intent={STATUS_INTENT[status]}
       size={size}

package/src/pedagogy/ui/GlossaryDefinition.tsx

@@ -0,0 +1,136 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import type { GlossaryEntry, GlossaryExample } from '../core/glossary.ts';
+
+import { InlineText } from './InlineText.tsx';
+import { exampleText } from './exampleText.ts';
+import { useGlossary } from './glossaryContext.ts';
+import type { ProseInk, ProseTone } from './pedagogyStyle.ts';
+import { MONOSPACE, PROSE_INK } from './pedagogyStyle.ts';
+
+/** Props of {@link GlossaryDefinition}. */
+export interface GlossaryDefinitionProps<TExample = GlossaryExample> {
+  /** The term to explain, already resolved from a marker. */
+  entry: GlossaryEntry<TExample>;
+  /**
+   * The ground it is drawn on: the dark plate of a tooltip, or the page, where
+   * a glossary lists every term.
+   * @default 'tooltip'
+   */
+  tone?: ProseTone;
+  /**
+   * Draws the illustration of one example; its note is still written under it.
+   * @default the surrounding provider's, and otherwise the code and the input
+   */
+  renderExample?: (example: TExample) => ReactNode;
+  /**
+   * Draws the code spans of the summary and of the notes.
+   * @default the surrounding provider's, and otherwise a monospace span
+   */
+  renderCode?: (code: string) => ReactNode;
+  /**
+   * Class names added to the root element.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * One definition: the term, one paragraph, then the worked examples.
+ *
+ * The tooltip a marker opens and the entry a glossary page lists are this one
+ * body on two grounds, so a term reads the same wherever it is looked up.
+ * @param props - The entry, and the ground it is drawn on.
+ * @returns The definition.
+ */
+export function GlossaryDefinition<TExample = GlossaryExample>(
+  props: GlossaryDefinitionProps<TExample>,
+): ReactElement {
+  const { className, entry, tone = 'tooltip' } = props;
+  const context = useGlossary();
+  const ink = PROSE_INK[tone];
+  const renderCode =
+    props.renderCode ??
+    context.renderCode ??
+    ((code: string) => <code style={codeStyle(ink)}>{code}</code>);
+  const renderExample = (props.renderExample ?? context.renderExample) as
+    ((example: TExample) => ReactNode) | undefined;
+
+  const items: ReactNode[] = [];
+  for (let position = 0; position < entry.examples.length; position++) {
+    const example = entry.examples[position] as TExample;
+    const note = exampleText(example, 'note');
+    items.push(
+      <li key={`example-${position}`}>
+        {renderExample === undefined ? (
+          <ExampleLine example={example} ink={ink} />
+        ) : (
+          renderExample(example)
+        )}
+        {note !== undefined && (
+          <div style={{ ...NOTE_STYLE, color: ink.muted }}>
+            <InlineText text={note} renderCode={renderCode} />
+          </div>
+        )}
+      </li>,
+    );
+  }
+
+  return (
+    <div
+      className={className}
+      style={tone === 'tooltip' ? TOOLTIP_BODY_STYLE : BODY_STYLE}
+    >
+      <div style={TITLE_STYLE}>{entry.title}</div>
+      <div style={{ ...SUMMARY_STYLE, color: ink.text }}>
+        <InlineText text={entry.summary} renderCode={renderCode} />
+      </div>
+      {items.length > 0 && <ul style={LIST_STYLE}>{items}</ul>}
+    </div>
+  );
+}
+
+function ExampleLine(props: {
+  example: unknown;
+  ink: ProseInk;
+}): ReactElement | null {
+  const { example, ink } = props;
+  const code = exampleText(example, 'code');
+  const input = exampleText(example, 'input');
+  if (code === undefined) return null;
+
+  return (
+    <>
+      <code style={codeStyle(ink)}>{code}</code>
+      {input !== undefined && <span>{` on ${input}`}</span>}
+    </>
+  );
+}
+
+function codeStyle(ink: ProseInk): CSSProperties {
+  return { fontFamily: MONOSPACE, fontWeight: 600, color: ink.code };
+}
+
+const BODY_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+};
+
+const TOOLTIP_BODY_STYLE: CSSProperties = { ...BODY_STYLE, maxWidth: 340 };
+
+const TITLE_STYLE: CSSProperties = { fontWeight: 600, fontSize: 13 };
+
+const SUMMARY_STYLE: CSSProperties = { fontSize: 12, lineHeight: 1.45 };
+
+const LIST_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+  margin: 0,
+  paddingLeft: 16,
+  fontSize: 12,
+  lineHeight: 1.4,
+};
+
+const NOTE_STYLE: CSSProperties = { fontStyle: 'italic' };

package/src/pedagogy/ui/GlossaryIndex.tsx

@@ -0,0 +1,171 @@
+import { InputGroup } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import { useMemo, useState } from 'react';
+
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+import type { Glossary, GlossaryExample } from '../core/glossary.ts';
+import { listGlossary } from '../core/glossarySearch.ts';
+
+import { GlossaryDefinition } from './GlossaryDefinition.tsx';
+import { useGlossary } from './glossaryContext.ts';
+
+/** Props of {@link GlossaryIndex}. */
+export interface GlossaryIndexProps<TExample = GlossaryExample> {
+  /**
+   * The terms to list.
+   * @default undefined — the glossary of the surrounding `GlossaryProvider`
+   */
+  glossary?: Glossary<TExample>;
+  /**
+   * Draws the illustration of an example.
+   * @default the surrounding provider's, and otherwise the code and the input
+   */
+  renderExample?: (example: TExample) => ReactNode;
+  /**
+   * Draws the code spans of the summaries and notes.
+   * @default the surrounding provider's, and otherwise a monospace span
+   */
+  renderCode?: (code: string) => ReactNode;
+  /**
+   * Whether a filter box sits over the list. It is left off the printed page.
+   * @default true
+   */
+  searchable?: boolean;
+  /**
+   * Placeholder and accessible name of the filter box.
+   * @default 'Filter terms…'
+   */
+  searchLabel?: string;
+  /**
+   * Width under which a column wraps to the next line, in pixels.
+   * @default 280
+   */
+  minColumnWidth?: number;
+  /**
+   * Prefix of the id each entry carries, so `#glossary-ring-closure` links to
+   * one term.
+   * @default 'glossary-'
+   */
+  idPrefix?: string;
+  /**
+   * Class the index carries, in addition to `glossary-index`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * Every term of a glossary on one page: searchable on screen, printable on
+ * paper, in alphabetical order of title.
+ *
+ * Each entry is the very definition a `[[marker]]` opens on hover, drawn on the
+ * page rather than on a tooltip, so a term never reads two ways. A filter
+ * matches the title, the summary and the text of the examples, since a student
+ * often remembers the notation and not the word it was filed under.
+ * @param props - The terms, and how the list is searched and laid out.
+ * @returns The index.
+ */
+export function GlossaryIndex<TExample = GlossaryExample>(
+  props: GlossaryIndexProps<TExample>,
+): ReactElement {
+  const {
+    glossary,
+    renderExample,
+    renderCode,
+    searchable = true,
+    searchLabel = 'Filter terms…',
+    minColumnWidth = 280,
+    idPrefix = 'glossary-',
+    className,
+  } = props;
+  const context = useGlossary();
+  const terms = (glossary ?? context.glossary) as Glossary<TExample>;
+  const [query, setQuery] = useState('');
+  const listings = useMemo(() => listGlossary(terms, query), [terms, query]);
+
+  return (
+    <div
+      className={joinClassNames('glossary-index', className)}
+      style={ROOT_STYLE}
+    >
+      {searchable && (
+        <div className="no-print" style={SEARCH_STYLE}>
+          <InputGroup
+            type="search"
+            leftIcon="search"
+            value={query}
+            placeholder={searchLabel}
+            aria-label={searchLabel}
+            autoComplete="off"
+            spellCheck={false}
+            onValueChange={setQuery}
+          />
+        </div>
+      )}
+      {listings.length === 0 ? (
+        <p style={EMPTY_STYLE}>{emptyMessage(query)}</p>
+      ) : (
+        <div style={gridStyle(minColumnWidth)}>
+          {listings.map(({ key, entry }) => (
+            <article
+              key={key}
+              id={`${idPrefix}${anchorOf(key)}`}
+              className="glossary-index-entry"
+              style={ENTRY_STYLE}
+            >
+              <GlossaryDefinition
+                entry={entry}
+                tone="page"
+                renderExample={renderExample}
+                renderCode={renderCode}
+              />
+            </article>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function emptyMessage(query: string): string {
+  const trimmed = query.trim();
+  return trimmed === ''
+    ? 'No term is defined yet.'
+    : `No term matches “${trimmed}”.`;
+}
+
+function anchorOf(key: string): string {
+  return key
+    .trim()
+    .replaceAll(/[^\p{L}\p{N}]+/gu, '-')
+    .replaceAll(/^-+|-+$/g, '');
+}
+
+function gridStyle(minColumnWidth: number): CSSProperties {
+  return {
+    display: 'grid',
+    gridTemplateColumns: `repeat(auto-fill, minmax(min(${minColumnWidth}px, 100%), 1fr))`,
+    gap: '12px 24px',
+    alignItems: 'start',
+  };
+}
+
+const ROOT_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 12,
+};
+
+const SEARCH_STYLE: CSSProperties = { maxWidth: 320 };
+
+const EMPTY_STYLE: CSSProperties = {
+  margin: 0,
+  color: TOKEN.textMuted,
+};
+
+const ENTRY_STYLE: CSSProperties = {
+  borderTop: `1px solid ${TOKEN.border}`,
+  breakInside: 'avoid',
+  paddingTop: 8,
+};

package/src/pedagogy/ui/GlossaryProvider.tsx

@@ -1,12 +1,28 @@
 import type { ReactElement, ReactNode } from 'react';
+import { useMemo } from 'react';
 
-import type { Glossary } from '../core/glossary.ts';
+import type { Glossary, GlossaryExample } from '../core/glossary.ts';
 
+import type { GlossaryContextValue } from './glossaryContext.ts';
 import { GlossaryContext } from './glossaryContext.ts';
 
-export interface GlossaryProviderProps {
+/** Props of {@link GlossaryProvider}. */
+export interface GlossaryProviderProps<TExample = GlossaryExample> {
   /** Every term the site defines, keyed by the lowercased text of a marker. */
-  glossary: Glossary;
+  glossary: Glossary<TExample>;
+  /**
+   * Draws the illustration of an example, wherever a definition below shows
+   * one: a structure for a SMILES, a typeset formula for LaTeX. The note of the
+   * example is still written under it. Needed whenever the examples are not
+   * `{ code, input, note }`.
+   * @default undefined — an example is its code, and the input it runs on
+   */
+  renderExample?: (example: TExample) => ReactNode;
+  /**
+   * Draws the code spans of the prose below.
+   * @default undefined — a plain `<code>`
+   */
+  renderCode?: (code: string) => ReactNode;
   /** The part of the page whose prose resolves its markers against it. */
   children: ReactNode;
 }
@@ -16,15 +32,27 @@ export interface GlossaryProviderProps {
  *
  * 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.
+ * jargon is linked, and they must define a term — and draw its examples — the
+ * same way.
+ * @param props - The terms, how their examples are drawn, and the tree that
+ * uses them.
  * @returns The tree, with the glossary in reach.
  */
-export function GlossaryProvider(props: GlossaryProviderProps): ReactElement {
-  const { glossary, children } = props;
+export function GlossaryProvider<TExample = GlossaryExample>(
+  props: GlossaryProviderProps<TExample>,
+): ReactElement {
+  const { glossary, renderExample, renderCode, children } = props;
+  const value = useMemo<GlossaryContextValue>(
+    () => ({
+      glossary,
+      renderExample: renderExample as GlossaryContextValue['renderExample'],
+      renderCode,
+    }),
+    [glossary, renderExample, renderCode],
+  );
 
   return (
-    <GlossaryContext.Provider value={glossary}>
+    <GlossaryContext.Provider value={value}>
       {children}
     </GlossaryContext.Provider>
   );

package/src/pedagogy/ui/GlossaryText.tsx

@@ -1,25 +1,32 @@
 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 type { Glossary, GlossaryExample } from '../core/glossary.ts';
+import { lookupGlossaryTerm } from '../core/glossary.ts';
+import { parseInlineMarks } from '../core/inlineMarks.ts';
 
+import { GlossaryDefinition } from './GlossaryDefinition.tsx';
+import type { GlossaryContextValue } from './glossaryContext.ts';
 import { useGlossary } from './glossaryContext.ts';
+import { plainCode, renderInlineSegments } from './inlineSegments.tsx';
+import { HOVER_OPEN_DELAY } from './pedagogyStyle.ts';
 
-export interface GlossaryTextProps {
+/** Props of {@link GlossaryText}. */
+export interface GlossaryTextProps<TExample = GlossaryExample> {
   /**
    * Authored prose. Every `[[term]]` — or `[[term|displayed text]]` — the
-   * glossary knows becomes a hoverable chip.
+   * glossary knows becomes a hoverable chip, and `` `code` ``, `**strong**`
+   * and `*emphasis*` are drawn as such.
    */
   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.
+   * holds. A page showing two vocabularies side by side passes its own here,
+   * with a `renderExample` when its examples have a shape of their own.
    * @default undefined — the glossary of the surrounding `GlossaryProvider`
    */
-  glossary?: Glossary;
+  glossary?: Glossary<TExample>;
   /**
    * Side the definition opens on.
    * @default 'bottom'
@@ -30,10 +37,21 @@ export interface GlossaryTextProps {
    * @default 'glossary-term'
    */
   className?: string;
+  /**
+   * Draws the illustration of an example inside a definition.
+   * @default the surrounding provider's, and otherwise the code and the input
+   */
+  renderExample?: (example: TExample) => ReactNode;
+  /**
+   * Draws a code span of the prose.
+   * @default the surrounding provider's, and otherwise a plain `<code>`
+   */
+  renderCode?: (code: string) => ReactNode;
 }
 
 /**
- * Render authored prose, turning its markers into hoverable definitions.
+ * Render authored prose, turning its markers into hoverable definitions and
+ * its inline marks into code, strong and emphasised runs.
  *
  * 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
@@ -41,124 +59,55 @@ export interface GlossaryTextProps {
  * @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 {
+export function GlossaryText<TExample = GlossaryExample>(
+  props: GlossaryTextProps<TExample>,
+): ReactElement {
   const {
     text,
     glossary,
     placement = 'bottom',
     className = 'glossary-term',
+    renderExample,
+    renderCode,
   } = 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;
+  const context = useGlossary();
+  const terms: Glossary<unknown> = glossary ?? context.glossary;
+  const segments = parseInlineMarks(text, { glossaryMarkers: true });
 
   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>
+    <>
+      {renderInlineSegments(segments, {
+        code: renderCode ?? context.renderCode ?? plainCode,
+        term: (term, shown) => {
+          const entry = lookupGlossaryTerm(terms, term);
+          if (entry === undefined) return shown;
+          return (
+            <Tooltip
+              content={
+                <GlossaryDefinition
+                  entry={entry}
+                  renderExample={
+                    renderExample as GlossaryContextValue['renderExample']
+                  }
+                  renderCode={renderCode}
+                />
+              }
+              hoverOpenDelay={HOVER_OPEN_DELAY}
+              placement={placement}
+            >
+              <span className={className} style={TERM_STYLE}>
+                {shown}
+              </span>
+            </Tooltip>
+          );
+        },
+      })}
+    </>
   );
 }
 
-/** 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: 'var(--border, #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: 'var(--surface-sunken, #f6f7f9)' };
-
-const NOTE_STYLE: CSSProperties = { fontStyle: 'italic', color: '#abb3bf' };