react-cheminfo 0.37.0 → 0.39.0

package/src/pedagogy/ui/GlossaryText.tsx

@@ -16,8 +16,8 @@ import { HOVER_OPEN_DELAY } from './pedagogyStyle.ts';
 export interface GlossaryTextProps<TExample = GlossaryExample> {
   /**
    * Authored prose. Every `[[term]]` — or `[[term|displayed text]]` — the
-   * glossary knows becomes a hoverable chip, and `` `code` ``, `**strong**`
-   * and `*emphasis*` are drawn as such.
+   * glossary knows becomes a hoverable chip, and `` `code` ``, `{{C6H6O}}`,
+   * `**strong**` and `*emphasis*` are drawn as such.
    */
   text: string;
   /**
@@ -47,6 +47,11 @@ export interface GlossaryTextProps<TExample = GlossaryExample> {
    * @default the surrounding provider's, and otherwise a plain `<code>`
    */
   renderCode?: (code: string) => ReactNode;
+  /**
+   * Draws a `{{C6H6O}}` of the prose.
+   * @default the surrounding provider's, and otherwise the formula as typed
+   */
+  renderMf?: (mf: string) => ReactNode;
 }
 
 /**
@@ -69,6 +74,7 @@ export function GlossaryText<TExample = GlossaryExample>(
     className = 'glossary-term',
     renderExample,
     renderCode,
+    renderMf,
   } = props;
   const context = useGlossary();
   const terms: Glossary<unknown> = glossary ?? context.glossary;
@@ -78,6 +84,7 @@ export function GlossaryText<TExample = GlossaryExample>(
     <>
       {renderInlineSegments(segments, {
         code: renderCode ?? context.renderCode ?? plainCode,
+        mf: renderMf ?? context.renderMf,
         term: (term, shown) => {
           const entry = lookupGlossaryTerm(terms, term);
           if (entry === undefined) return shown;
@@ -94,6 +101,7 @@ export function GlossaryText<TExample = GlossaryExample>(
               }
               hoverOpenDelay={HOVER_OPEN_DELAY}
               placement={placement}
+              popoverClassName="help-tooltip"
             >
               <span className={className} style={TERM_STYLE}>
                 {shown}

package/src/pedagogy/ui/InlineText.tsx

@@ -2,13 +2,14 @@ import type { ReactElement, ReactNode } from 'react';
 
 import { parseInlineMarks } from '../core/inlineMarks.ts';
 
+import { useGlossary } from './glossaryContext.ts';
 import { plainCode, renderInlineSegments } from './inlineSegments.tsx';
 
 /** Props of {@link InlineText}. */
 export interface InlineTextProps {
   /**
-   * Authored prose: `` `code` ``, `**strong**` and `*emphasis*`. Anything else,
-   * `[[markers]]` included, is shown as typed.
+   * Authored prose: `` `code` ``, `{{C6H6O}}`, `**strong**` and `*emphasis*`.
+   * Anything else, `[[markers]]` included, is shown as typed.
    */
   text: string;
   /**
@@ -17,6 +18,12 @@ export interface InlineTextProps {
    * @default a plain `<code>`
    */
   renderCode?: (code: string) => ReactNode;
+  /**
+   * Draws a `{{C6H6O}}`: as a formula, with `react-mf`.
+   * @default the surrounding `GlossaryProvider`'s, and otherwise the formula
+   * as typed
+   */
+  renderMf?: (mf: string) => ReactNode;
 }
 
 /**
@@ -31,9 +38,19 @@ export interface InlineTextProps {
  * @returns The prose, with its marks drawn.
  */
 export function InlineText(props: InlineTextProps): ReactElement {
-  const { text, renderCode = plainCode } = props;
+  const context = useGlossary();
+  const {
+    text,
+    renderCode = context.renderCode ?? plainCode,
+    renderMf = context.renderMf,
+  } = props;
 
   return (
-    <>{renderInlineSegments(parseInlineMarks(text), { code: renderCode })}</>
+    <>
+      {renderInlineSegments(parseInlineMarks(text), {
+        code: renderCode,
+        mf: renderMf,
+      })}
+    </>
   );
 }

package/src/pedagogy/ui/ReferenceSectionBlock.tsx

@@ -4,6 +4,7 @@ import { ClickToCopy } from '../../clipboard/ui/ClickToCopy.tsx';
 import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
 
+import { InlineText } from './InlineText.tsx';
 import type { SyntaxTooltipContent } from './SyntaxTooltip.tsx';
 import { SyntaxTooltip } from './SyntaxTooltip.tsx';
 import { MONOSPACE } from './pedagogyStyle.ts';
@@ -12,7 +13,10 @@ import { MONOSPACE } from './pedagogyStyle.ts';
 export interface ReferenceRow {
   /** The construct itself, set in monospace. */
   syntax: string;
-  /** What it does, in one line — short enough to read on paper. */
+  /**
+   * What it does, in one line — short enough to read on paper. Authored prose,
+   * so a `{{C6H6O}}` in it is drawn as a formula and a `` `code` `` as code.
+   */
   description: string;
   /**
    * The longer story, opened by hovering the row. A sparse section is meant to
@@ -118,7 +122,9 @@ function ReferenceRowLine(props: {
           {row.syntax}
         </ClickToCopy>
       </span>
-      <span style={DESCRIPTION_STYLE}>{row.description}</span>
+      <span style={DESCRIPTION_STYLE}>
+        <InlineText text={row.description} />
+      </span>
     </span>
   );
   if (row.tooltip === undefined) return line;

package/src/pedagogy/ui/SyntaxTooltip.tsx

@@ -3,6 +3,7 @@ import { Tooltip } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
 
 import { useChromeT } from '../../i18n/ui/useT.ts';
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
 import type { GlossaryExample } from '../core/glossary.ts';
 
 import { HOVER_OPEN_DELAY, MONOSPACE, PROSE_INK } from './pedagogyStyle.ts';
@@ -98,6 +99,7 @@ export function SyntaxTooltip(props: SyntaxTooltipProps): ReactElement {
       hoverOpenDelay={HOVER_OPEN_DELAY}
       placement={placement}
       isOpen={isOpen}
+      popoverClassName="help-tooltip"
     >
       {children}
     </Tooltip>
@@ -164,7 +166,6 @@ const BODY_STYLE: CSSProperties = {
   display: 'flex',
   flexDirection: 'column',
   gap: 6,
-  maxWidth: 360,
 };
 
 const HEADER_STYLE: CSSProperties = {
@@ -175,9 +176,10 @@ const HEADER_STYLE: CSSProperties = {
 };
 
 const SYNTAX_STYLE: CSSProperties = {
-  background: PROSE_INK.tooltip.rule,
+  background: TOKEN.surfaceSunken,
+  border: `1px solid ${PROSE_INK.rule}`,
   borderRadius: 3,
-  color: '#ffffff',
+  color: PROSE_INK.code,
   fontFamily: MONOSPACE,
   fontSize: 14,
   fontWeight: 600,
@@ -187,20 +189,20 @@ const SYNTAX_STYLE: CSSProperties = {
 const NAME_STYLE: CSSProperties = { fontWeight: 600, fontSize: 13 };
 
 const TAG_STYLE: CSSProperties = {
-  color: PROSE_INK.tooltip.muted,
+  color: PROSE_INK.muted,
   fontSize: 11,
 };
 
 const SUMMARY_STYLE: CSSProperties = { fontSize: 12, lineHeight: 1.4 };
 
 const DETAIL_STYLE: CSSProperties = {
-  color: PROSE_INK.tooltip.text,
+  color: PROSE_INK.text,
   fontSize: 12,
   lineHeight: 1.45,
 };
 
 const EXAMPLE_STYLE: CSSProperties = {
-  borderTop: `1px solid ${PROSE_INK.tooltip.rule}`,
+  borderTop: `1px solid ${PROSE_INK.rule}`,
   display: 'flex',
   flexDirection: 'column',
   gap: 2,
@@ -210,18 +212,18 @@ const EXAMPLE_STYLE: CSSProperties = {
 const ROW_STYLE: CSSProperties = { display: 'flex', gap: 6, fontSize: 12 };
 
 const LABEL_STYLE: CSSProperties = {
-  color: PROSE_INK.tooltip.muted,
+  color: PROSE_INK.muted,
   flex: '0 0 68px',
 };
 
 const VALUE_STYLE: CSSProperties = {
-  color: PROSE_INK.tooltip.text,
+  color: PROSE_INK.text,
   fontFamily: MONOSPACE,
   overflowWrap: 'anywhere',
 };
 
 const NOTE_STYLE: CSSProperties = {
-  color: PROSE_INK.tooltip.muted,
+  color: PROSE_INK.muted,
   fontSize: 12,
   fontStyle: 'italic',
   marginTop: 2,

package/src/pedagogy/ui/TutorialStepStrip.tsx

@@ -1,8 +1,9 @@
-import { Button, Tag, Tooltip } from '@blueprintjs/core';
+import { Button, Tag } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
 
 import { clamp } from '../../format/core/clamp.ts';
 import { useChromeT } from '../../i18n/ui/useT.ts';
+import { ActionTooltip } from '../../shared/ui/ActionTooltip.tsx';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
 import type { ExerciseLevel } from '../core/types.ts';
 
@@ -150,24 +151,14 @@ function LevelStrip(props: LevelStripProps): ReactElement {
     const step = steps[position] as TutorialStripStep;
     const active = position === activeIndex;
     buttons.push(
-      <Tooltip
+      <StepButton
         key={step.id ?? position}
-        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>,
+        step={step}
+        position={position}
+        colours={colours}
+        active={active}
+        onSelect={onSelect}
+      />,
     );
   }
 
@@ -179,6 +170,47 @@ function LevelStrip(props: LevelStripProps): ReactElement {
   );
 }
 
+interface StepButtonProps {
+  step: TutorialStripStep;
+  position: number;
+  colours: TutorialLevelColours;
+  active: boolean;
+  onSelect: (index: number) => void;
+}
+
+/**
+ * One numbered step, naming itself on hover.
+ *
+ * The name is held by {@link ActionTooltip} rather than by Blueprint: pressing
+ * a number within the hover delay would otherwise open the card afterwards,
+ * over the step it has just walked away from.
+ * @param props - The step, where it sits, and what picking it does.
+ * @returns The button.
+ */
+function StepButton(props: StepButtonProps): ReactElement {
+  const { step, position, colours, active, onSelect } = props;
+
+  return (
+    <ActionTooltip
+      content={step.title}
+      delay={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>
+    </ActionTooltip>
+  );
+}
+
 function positionsOfLevel(
   steps: readonly TutorialStripStep[],
   level: ExerciseLevel,

package/src/pedagogy/ui/glossaryContext.ts

@@ -26,6 +26,13 @@ export interface GlossaryContextValue {
    * @default undefined — a plain `<code>`
    */
   renderCode?: (code: string) => ReactNode;
+  /**
+   * Draws a `{{C6H6O}}` of the prose. A chemistry site passes
+   * `(mf) => <MF mf={mf} />` from `react-mf` here, once, so that every formula
+   * below reads as a formula rather than as a line of digits.
+   * @default undefined — the formula as typed
+   */
+  renderMf?: (mf: string) => ReactNode;
 }
 
 /**

package/src/pedagogy/ui/index.ts

@@ -41,7 +41,7 @@ export type {
   SyntaxTooltipProps,
 } from './SyntaxTooltip.tsx';
 export { SyntaxTooltip } from './SyntaxTooltip.tsx';
-export type { ProseTone } from './pedagogyStyle.ts';
+export type { ProseInk } from './pedagogyStyle.ts';
 export type { TestCaseListProps } from './TestCaseList.tsx';
 export { TestCaseList } from './TestCaseList.tsx';
 export type {

package/src/pedagogy/ui/inlineSegments.tsx

@@ -7,6 +7,11 @@ import type { InlineSegment } from '../core/inlineMarks.ts';
 interface InlineRenderers {
   /** Draws a code span, from the text between its backticks. */
   code: (code: string) => ReactNode;
+  /**
+   * Draws a molecular formula, from the text between its braces.
+   * @default undefined — the formula as typed, which no chemistry site wants
+   */
+  mf?: (mf: string) => ReactNode;
   /**
    * Draws a glossary marker, from its lowercased term and the text to show.
    * @default undefined — the text, as plain prose
@@ -53,6 +58,8 @@ function renderSegment(
       return segment.text;
     case 'code':
       return renderers.code(segment.text);
+    case 'mf':
+      return renderers.mf === undefined ? segment.mf : renderers.mf(segment.mf);
     case 'term':
       return renderers.term === undefined
         ? segment.text

package/src/pedagogy/ui/pedagogyStyle.ts

@@ -1,11 +1,9 @@
 /**
  * What the pedagogy components share about how they look: how long a pointer
  * rests before a definition opens, the monospace stack, and the ink prose is
- * set in on each of the two grounds it is shown on.
+ * set in.
  */
 
-import { Colors } from '@blueprintjs/core';
-
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
 
 /** Long enough that the pointer can cross a chip or a row without opening it. */
@@ -15,10 +13,7 @@ export const HOVER_OPEN_DELAY = 150;
 export const MONOSPACE =
   'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace';
 
-/** Where prose is drawn: on the dark plate of a tooltip, or on the page. */
-export type ProseTone = 'tooltip' | 'page';
-
-/** The colours prose is set in on one ground. */
+/** The colours prose is set in. */
 export interface ProseInk {
   /** The body of a paragraph. */
   text: string;
@@ -31,23 +26,16 @@ export interface ProseInk {
 }
 
 /**
- * The ink of each ground.
+ * The one ink, because there is one ground.
  *
- * A Blueprint tooltip is the same dark plate on every site, so its ink is white
- * at decreasing strength, read off the plate rather than off the family tokens,
- * which are written for a light page. The page ink is the tokens.
+ * A definition, a documented construct and a help card are the same job, and
+ * the family answers it with one card: `help-tooltip` in `chrome.css`, light,
+ * on a border and a shadow. So the prose here is the family's tokens wherever
+ * it is read — on a page, or on that card.
  */
-export const PROSE_INK: Readonly<Record<ProseTone, ProseInk>> = {
-  tooltip: {
-    text: 'rgb(255 255 255 / 82%)',
-    muted: 'rgb(255 255 255 / 62%)',
-    code: Colors.BLUE5,
-    rule: 'rgb(255 255 255 / 15%)',
-  },
-  page: {
-    text: TOKEN.text,
-    muted: TOKEN.textMuted,
-    code: TOKEN.text,
-    rule: TOKEN.border,
-  },
+export const PROSE_INK: ProseInk = {
+  text: TOKEN.text,
+  muted: TOKEN.textMuted,
+  code: TOKEN.text,
+  rule: TOKEN.border,
 };

package/src/range/core/index.ts

@@ -0,0 +1,11 @@
+export type { RangeBounds, RangeDomain, RangeHandles } from './rangeBounds.ts';
+export {
+  OPEN_RANGE,
+  isRangeBounded,
+  isRangeDomain,
+  movedRange,
+  rangeHandles,
+  sameRange,
+  settleHandles,
+} from './rangeBounds.ts';
+export { rangeHistogramPath } from './rangeHistogram.ts';

package/src/range/core/rangeBounds.ts

@@ -0,0 +1,143 @@
+/**
+ * What a range filter keeps, and how its two handles map to it.
+ *
+ * A filter is two bounds, either of which may be left open. A handle parked at
+ * the end of the track is an open side rather than a bound at the track's end,
+ * because the track only covers the values the page knows about: a molecule
+ * heavier than the heaviest one in the statistics must not be cut by a filter
+ * nobody touched.
+ */
+
+import { clamp } from '../../format/core/clamp.ts';
+import { snapToStep } from '../../number/core/numberText.ts';
+
+/** A lowest and a highest value kept, either of which may be left open. */
+export interface RangeBounds {
+  /** The lowest value kept, or `null` when nothing is cut from below. */
+  readonly min: number | null;
+  /** The highest value kept, or `null` when nothing is cut from above. */
+  readonly max: number | null;
+}
+
+/** The two ends of a slider's track, low first. */
+export type RangeDomain = readonly [number, number];
+
+/** Where the two handles of a slider stand, low first. */
+export type RangeHandles = readonly [number, number];
+
+/** A range that keeps everything. */
+export const OPEN_RANGE: RangeBounds = Object.freeze({ min: null, max: null });
+
+/**
+ * Whether a range cuts anything at all.
+ * @param range - The range.
+ * @returns Whether either side carries a bound.
+ */
+export function isRangeBounded(range: RangeBounds): boolean {
+  return range.min !== null || range.max !== null;
+}
+
+/**
+ * Whether two ranges keep the same values.
+ * @param left - One range.
+ * @param right - The other.
+ * @returns Whether both sides agree, an open side matching only an open side.
+ */
+export function sameRange(left: RangeBounds, right: RangeBounds): boolean {
+  return Object.is(left.min, right.min) && Object.is(left.max, right.max);
+}
+
+/**
+ * Whether a track can be drawn: two finite ends, the high one above the low.
+ * Statistics that have not arrived yet are usually a track of `[0, 0]`.
+ * @param domain - The two ends.
+ * @returns Whether a slider can be laid along it.
+ */
+export function isRangeDomain(domain: RangeDomain): boolean {
+  const [low, high] = domain;
+  return Number.isFinite(low) && Number.isFinite(high) && high > low;
+}
+
+/**
+ * Where the handles stand for a range: an open side at the end of the track,
+ * and a bound past the track held at its end.
+ * @param range - The range.
+ * @param domain - The track, already checked with {@link isRangeDomain}.
+ * @returns The two handle positions, low first.
+ */
+export function rangeHandles(
+  range: RangeBounds,
+  domain: RangeDomain,
+): RangeHandles {
+  const [low, high] = domain;
+  const start = range.min === null ? low : clamp(range.min, low, high);
+  const end = range.max === null ? high : clamp(range.max, low, high);
+  return start <= end ? [start, end] : [end, start];
+}
+
+/**
+ * The range two handles stand for once they have moved.
+ *
+ * Only a handle that moved changes its side. A bound past the end of the track
+ * sits at that end, and dragging the other handle must not turn it into an
+ * open side; a handle the reader took to the end of the track, on the other
+ * hand, opens its side.
+ * @param from - The range before the handles moved.
+ * @param handles - Where the handles are now.
+ * @param domain - The track.
+ * @returns The range the reader asked for.
+ */
+export function movedRange(
+  from: RangeBounds,
+  handles: RangeHandles,
+  domain: RangeDomain,
+): RangeBounds {
+  const [low, high] = domain;
+  const [start, end] = rangeHandles(from, domain);
+  return {
+    min:
+      handles[0] === start ? from.min : handles[0] <= low ? null : handles[0],
+    max: handles[1] === end ? from.max : handles[1] >= high ? null : handles[1],
+  };
+}
+
+/**
+ * Where handles settle while they are dragged: a moved handle onto the step
+ * grid laid from the low end of the track, an untouched one where it stood.
+ *
+ * Snapping the untouched handle too would move a bound the reader typed, say
+ * `1.23` on a track stepped by `0.5`, the moment the other handle is dragged.
+ * The ends of the track are kept even when they are off the grid, since an end
+ * is what opens a side.
+ * @param next - Where the slider reports the handles.
+ * @param from - The range before the drag started.
+ * @param step - The grid spacing.
+ * @param domain - The track.
+ * @returns The handle positions to draw and to report.
+ */
+export function settleHandles(
+  next: RangeHandles,
+  from: RangeBounds,
+  step: number,
+  domain: RangeDomain,
+): RangeHandles {
+  const [start, end] = rangeHandles(from, domain);
+  return [
+    next[0] === start ? start : snapHandle(next[0], step, domain),
+    next[1] === end ? end : snapHandle(next[1], step, domain),
+  ];
+}
+
+/**
+ * One handle moved onto the step grid, the ends of the track kept as they are.
+ * @param value - Where the handle was dropped.
+ * @param step - The grid spacing.
+ * @param domain - The track.
+ * @returns The position the handle settles on.
+ */
+function snapHandle(value: number, step: number, domain: RangeDomain): number {
+  const [low, high] = domain;
+  if (value <= low) return low;
+  if (value >= high) return high;
+  return clamp(snapToStep(value, step, low), low, high);
+}

package/src/range/core/rangeHistogram.ts

@@ -0,0 +1,38 @@
+/**
+ * The outline of a histogram whose bins split the track into equal widths, as
+ * SVG path data in a box one unit wide and one unit tall.
+ *
+ * One stepped outline rather than a rectangle per bin: adjacent rectangles
+ * leave a hairline seam between them wherever their shared edge falls between
+ * two pixels, and a thousand bins would be two thousand elements.
+ * @param counts - One count per bin, from the low end of the track.
+ * @returns The path data, the tallest bin reaching the top; empty when nothing
+ * was counted.
+ */
+export function rangeHistogramPath(counts: ArrayLike<number>): string {
+  const bins = counts.length;
+  let tallest = 0;
+  for (let index = 0; index < bins; index++) {
+    const count = counts[index] as number;
+    if (count > tallest) tallest = count;
+  }
+  if (tallest <= 0) return '';
+
+  let path = 'M0 1';
+  for (let index = 0; index < bins; index++) {
+    const count = counts[index] as number;
+    const height = count > 0 ? count / tallest : 0;
+    path += `V${trim(1 - height)}H${trim((index + 1) / bins)}`;
+  }
+  return `${path}V1Z`;
+}
+
+/**
+ * A coordinate written with the five decimals a box of a few hundred pixels
+ * can use.
+ * @param value - The coordinate.
+ * @returns Its text.
+ */
+function trim(value: number): string {
+  return String(Math.round(value * 1e5) / 1e5);
+}

package/src/range/ui/RangeHistogram.tsx

@@ -0,0 +1,49 @@
+import type { ReactElement } from 'react';
+import { useId, useMemo } from 'react';
+
+import { rangeHistogramPath } from '../core/rangeHistogram.ts';
+
+/** What the histogram over a range slider needs. */
+export interface RangeHistogramProps {
+  /** One count per bin, the bins splitting the track into equal widths. */
+  counts: ArrayLike<number>;
+  /** Where the kept part starts, as a fraction of the track. */
+  start: number;
+  /** Where it ends. */
+  end: number;
+}
+
+/**
+ * How the values are spread along the track, the part the handles keep drawn
+ * in the brand colour. The outline is drawn twice, the second copy clipped to
+ * the handles, so a drag moves one rectangle and the outline is never redrawn.
+ * @param props - See {@link RangeHistogramProps}.
+ * @returns The histogram, hidden from a screen reader: the values under the
+ * track already say what it keeps.
+ */
+export function RangeHistogram(props: RangeHistogramProps): ReactElement {
+  const { counts, start, end } = props;
+  const clip = `range-histogram-${useId().replaceAll(/\W/g, '')}`;
+  const outline = useMemo(() => rangeHistogramPath(counts), [counts]);
+
+  return (
+    <svg
+      className="range-slider__histogram"
+      viewBox="0 0 1 1"
+      preserveAspectRatio="none"
+      aria-hidden="true"
+    >
+      <defs>
+        <clipPath id={clip}>
+          <rect x={start} y={0} width={Math.max(end - start, 0)} height={1} />
+        </clipPath>
+      </defs>
+      <path className="range-slider__bars" d={outline} />
+      <path
+        className="range-slider__bars range-slider__bars--kept"
+        d={outline}
+        clipPath={`url(#${clip})`}
+      />
+    </svg>
+  );
+}