react-cheminfo 0.8.0 → 0.9.0

package/src/orbital/ui/viewer.ts

@@ -26,12 +26,14 @@ import {
   DEFAULT_CAMERA_DURATION,
   DEFAULT_SPIN_SPEED,
   frameOrbital,
+  refitOrbital,
   setSpin,
 } from './camera.ts';
 import type { AxesStyle } from './renderAxes.ts';
 import { clearOrbitalAxes, renderOrbitalAxes } from './renderAxes.ts';
 import type { VolumeStyle } from './renderVolume.ts';
 import { clearSampledVolume, renderSampledVolume } from './renderVolume.ts';
+import { createSerialRunner } from './serial.ts';
 
 /** Settings fixed for the life of a viewer. */
 export interface OrbitalViewerOptions {
@@ -64,7 +66,12 @@ export function createOrbitalViewer(
  */
 export class OrbitalViewer {
   readonly #model: PluginViewModel;
+  // One canvas, so one operation at a time — see `serial.ts` for what
+  // interleaving two of them does to the scene.
+  readonly #serial = createSerialRunner();
   #disposed = false;
+  /** Extent the camera was last fitted to; `null` before it has been placed. */
+  #fittedRadius: number | null = null;
 
   /** Resolves once the canvas exists; every method awaits it internally. */
   readonly ready: Promise<void>;
@@ -78,7 +85,16 @@ export class OrbitalViewer {
         canvas3d: {
           ...spec.canvas3d,
           renderer: { backgroundColor: Color.fromHexStyle(background) },
-          camera: { helper: { axes: { name: 'off', params: {} } } },
+          camera: {
+            helper: { axes: { name: 'off', params: {} } },
+            // The camera is ours alone. Molstar reframes itself whenever a
+            // scene commit leaves the renderable count at zero, which is what
+            // replacing one orbital by another does — the old surfaces are
+            // removed and committed before the new ones exist — and it frames
+            // the whole sampled box rather than the isosurface inside it,
+            // which leaves the orbital a fifth of the frame wide.
+            manualReset: true,
+          },
         },
       },
     });
@@ -159,9 +175,49 @@ export class OrbitalViewer {
   ): Promise<void> {
     return this.#run((plugin) => {
       frameOrbital(plugin, orbitalRadius, durationMs);
+      this.#fittedRadius = orbitalRadius ?? null;
     });
   }
 
+  /**
+   * Fit a newly drawn orbital without disturbing the view.
+   *
+   * The first call frames the orbital, since there is no view to keep yet.
+   * Later ones leave the rotation and the zoom the student set and only rescale
+   * them when the drawn extent changed — clicking through a shell must not
+   * throw their view away.
+   * @param orbitalRadius - Extent of the drawn surface, as `showOrbital`
+   * returned it.
+   * @param durationMs - Transition length; 0 jumps.
+   * @returns Nothing, once the camera has been set.
+   */
+  refit(
+    orbitalRadius?: number,
+    durationMs = DEFAULT_CAMERA_DURATION,
+  ): Promise<void> {
+    const fitted = this.#fittedRadius;
+    if (fitted === null || orbitalRadius === undefined) {
+      return this.frame(orbitalRadius, durationMs);
+    }
+    return this.#run((plugin) => {
+      refitOrbital(plugin, fitted, orbitalRadius, durationMs);
+      this.#fittedRadius = orbitalRadius;
+    });
+  }
+
+  /**
+   * Put the camera back where the orbital was first framed from.
+   *
+   * The counterpart of `refit`: since a view is now kept across a change of
+   * orbital, a student who has turned the atom into an unreadable angle needs
+   * one way back.
+   * @param durationMs - Transition length; 0 jumps.
+   * @returns Nothing, once the camera has been set.
+   */
+  resetView(durationMs = DEFAULT_CAMERA_DURATION): Promise<void> {
+    return this.frame(this.#fittedRadius ?? undefined, durationMs);
+  }
+
   /**
    * Turn the automatic spin on or off.
    * @param spinning - Whether the scene should keep turning.
@@ -199,23 +255,26 @@ export class OrbitalViewer {
   }
 
   /**
-   * Wait for initialisation, then run `action` on the plugin. Resolves to
-   * `undefined` when the viewer was disposed, before the call or while `action`
-   * was still running; an initialisation failure still reaches the caller.
+   * Wait for the operations queued before this one and for initialisation,
+   * then run `action` on the plugin. Resolves to `undefined` when the viewer
+   * was disposed, before the call or while `action` was still running; an
+   * initialisation failure still reaches the caller.
    * @param action - What to run once the canvas is ready.
    * @returns What `action` returned, or `undefined` when disposed.
    */
-  async #run<Result>(
+  #run<Result>(
     action: (plugin: PluginContext) => Result | Promise<Result>,
   ): Promise<Result | undefined> {
-    if (this.#disposed) return undefined;
-    await this.ready;
-    if (this.#disposed) return undefined;
-    try {
-      return await action(this.#model.plugin);
-    } catch (error) {
+    return this.#serial.run(async () => {
       if (this.#disposed) return undefined;
-      throw error;
-    }
+      await this.ready;
+      if (this.#disposed) return undefined;
+      try {
+        return await action(this.#model.plugin);
+      } catch (error) {
+        if (this.#disposed) return undefined;
+        throw error;
+      }
+    });
   }
 }

package/src/pedagogy/ui/ExerciseProgressHeader.tsx

@@ -129,7 +129,7 @@ const ROW_STYLE: CSSProperties = {
 const COUNT_STYLE: CSSProperties = { fontWeight: 600 };
 
 const PERCENT_STYLE: CSSProperties = {
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   flex: '1 1 auto',
   fontSize: 12,
 };

package/src/pedagogy/ui/GlossaryText.tsx

@@ -140,7 +140,7 @@ const TITLE_STYLE: CSSProperties = { fontWeight: 600, fontSize: 13 };
 const SUMMARY_STYLE: CSSProperties = {
   fontSize: 12,
   lineHeight: 1.45,
-  color: '#d3d8de',
+  color: 'var(--border, #d3d8de)',
 };
 
 const LIST_STYLE: CSSProperties = {
@@ -159,6 +159,6 @@ const CODE_STYLE: CSSProperties = {
   color: '#8abbff',
 };
 
-const INPUT_STYLE: CSSProperties = { color: '#f6f7f9' };
+const INPUT_STYLE: CSSProperties = { color: 'var(--surface-sunken, #f6f7f9)' };
 
 const NOTE_STYLE: CSSProperties = { fontStyle: 'italic', color: '#abb3bf' };

package/src/pedagogy/ui/ReferenceSectionBlock.tsx

@@ -140,7 +140,10 @@ function syntaxStyle(
     fontWeight: 600,
     color: '#1c2127',
     ...(interactive
-      ? { borderBottom: '1px dotted #5b6875', alignSelf: 'flex-start' }
+      ? {
+          borderBottom: '1px dotted var(--text-muted, #5b6875)',
+          alignSelf: 'flex-start',
+        }
       : {}),
   };
 }
@@ -153,7 +156,7 @@ const SECTION_STYLE: CSSProperties = {
 
 const INTRO_STYLE: CSSProperties = {
   margin: '0 0 4px',
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   fontSize: 12,
 };
 

package/src/pedagogy/ui/SyntaxTooltip.tsx

@@ -191,7 +191,7 @@ const TAG_STYLE: CSSProperties = { color: '#abb3bf', fontSize: 11 };
 const SUMMARY_STYLE: CSSProperties = { fontSize: 12, lineHeight: 1.4 };
 
 const DETAIL_STYLE: CSSProperties = {
-  color: '#d3d8de',
+  color: 'var(--border, #d3d8de)',
   fontSize: 12,
   lineHeight: 1.45,
 };
@@ -209,7 +209,7 @@ 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',
+  color: 'var(--surface-sunken, #f6f7f9)',
   fontFamily: MONOSPACE,
   overflowWrap: 'anywhere',
 };

package/src/pedagogy/ui/TutorialStepStrip.tsx

@@ -253,4 +253,7 @@ const PAGER_STYLE: CSSProperties = {
   paddingTop: 2,
 };
 
-const HINT_STYLE: CSSProperties = { color: '#5b6875', fontSize: 11 };
+const HINT_STYLE: CSSProperties = {
+  color: 'var(--text-muted, #5b6875)',
+  fontSize: 11,
+};

package/src/periodic/ui/CategoryLegend.tsx

@@ -74,7 +74,7 @@ export function CategoryLegend(props: CategoryLegendProps): ReactElement {
 }
 
 const legendStyle = {
-  color: 'rgb(95 107 124)',
+  color: 'var(--text-muted, rgb(95 107 124))',
   display: 'flex',
   flexWrap: 'wrap',
   fontSize: 11,

package/src/periodic/ui/PeriodicTableChrome.tsx

@@ -145,7 +145,7 @@ function HeaderCell(props: HeaderCellProps): ReactElement {
 
 const headerStyle = {
   alignItems: 'center',
-  color: 'rgb(95 107 124)',
+  color: 'var(--text-muted, rgb(95 107 124))',
   display: 'flex',
   fontSize: 'clamp(0.4rem, 1.9cqw, 0.62rem)',
   justifyContent: 'center',
@@ -163,7 +163,7 @@ const markerStyle = {
   alignItems: 'center',
   border: '1px dashed rgb(182 191 204)',
   borderRadius: 3,
-  color: 'rgb(95 107 124)',
+  color: 'var(--text-muted, rgb(95 107 124))',
   display: 'flex',
   fontSize: 'clamp(0.36rem, 1.7cqw, 0.55rem)',
   justifyContent: 'center',

package/src/seo/vite/ogCard.ts

@@ -1,3 +1,4 @@
+// tokens-ok: file — the card is an image built outside any page, so it has no tokens to read.
 /**
  * The 1200×630 card a link to a site unfurls into, as a page to screenshot.
  *

package/src/share/ui/ShareDialogContent.tsx

@@ -28,7 +28,10 @@ import type { ShareDialogProps, ShareDraft } from './ShareDialog.tsx';
 import { SharePartOptions } from './SharePartOptions.tsx';
 import { withPart } from './draft.ts';
 
-const LEAD_STYLE: CSSProperties = { marginTop: 0, color: '#5b6875' };
+const LEAD_STYLE: CSSProperties = {
+  marginTop: 0,
+  color: 'var(--text-muted, #5b6875)',
+};
 const SECTION_STYLE: CSSProperties = { marginBottom: 18 };
 const ACTIONS_STYLE: CSSProperties = {
   display: 'flex',
@@ -39,7 +42,7 @@ const ACTIONS_STYLE: CSSProperties = {
 const HINT_STYLE: CSSProperties = {
   display: 'block',
   marginLeft: 26,
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   fontSize: 12,
 };
 

package/src/share/ui/SharePartOptions.tsx

@@ -8,7 +8,7 @@ const OPTION_STYLE: CSSProperties = { marginBottom: 8 };
 const DESCRIPTION_STYLE: CSSProperties = {
   display: 'block',
   marginLeft: 26,
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   fontSize: 12,
 };
 

package/src/slides/core/demoLinks.ts

@@ -0,0 +1,113 @@
+/**
+ * The links a slide hands over to the live tool.
+ *
+ * A demo link is a paragraph that is exactly one Markdown link to an in-app
+ * route. It is parsed by hand rather than by a Markdown library because the
+ * labels are chemistry — `[M+H]⁺` opens a bracket the label closes itself, and
+ * a formula such as `H(OCH2CH2)10` puts parentheses inside the URL — and both
+ * defeat a naive `\[(.*)\]\((.*)\)` pattern.
+ */
+
+/** One link a slide offers as a live demo. */
+export interface DemoLinkSpec {
+  /** The link text, which may itself contain balanced brackets. */
+  label: string;
+  /** Where it goes; a demo link always targets an in-app route. */
+  href: string;
+}
+
+/**
+ * Read a paragraph that is exactly one Markdown link `[label](url)` and nothing
+ * else, counting brackets so a label may hold its own pair, and accepting the
+ * angle-bracketed URL form `[label](<url>)` for a URL holding parentheses.
+ * @param text - The paragraph text.
+ * @returns The link, or `null` when the paragraph is anything else.
+ */
+export function parseSingleLink(text: string): DemoLinkSpec | null {
+  const source = text.trim();
+  if (!source.startsWith('[')) return null;
+
+  let depth = 0;
+  let labelEnd = -1;
+  for (let index = 0; index < source.length; index++) {
+    const char = source[index];
+    if (char === '[') {
+      depth++;
+    } else if (char === ']') {
+      depth--;
+      if (depth === 0) {
+        labelEnd = index;
+        break;
+      }
+    }
+  }
+  if (labelEnd === -1 || source[labelEnd + 1] !== '(') return null;
+
+  const label = source.slice(1, labelEnd);
+  let rest = source.slice(labelEnd + 2);
+  let href: string;
+
+  if (rest.startsWith('<')) {
+    const close = rest.indexOf('>');
+    if (close === -1 || rest[close + 1] !== ')') return null;
+    href = rest.slice(1, close);
+    rest = rest.slice(close + 2);
+  } else {
+    let parenDepth = 1;
+    let urlEnd = -1;
+    for (let index = 0; index < rest.length; index++) {
+      const char = rest[index];
+      if (char === '(') {
+        parenDepth++;
+      } else if (char === ')') {
+        parenDepth--;
+        if (parenDepth === 0) {
+          urlEnd = index;
+          break;
+        }
+      }
+    }
+    if (urlEnd === -1) return null;
+    href = rest.slice(0, urlEnd);
+    rest = rest.slice(urlEnd + 1);
+  }
+
+  if (rest.trim() !== '') return null;
+  return { label, href };
+}
+
+/**
+ * Split a slide body into its Markdown and the run of demo links that closes
+ * it. External links and ordinary paragraphs stay in the body, so a slide that
+ * merely cites a URL keeps it where the author wrote it.
+ * @param body - The slide Markdown body.
+ * @returns The body without its trailing demo links, and those links in order.
+ */
+export function splitDemoLinks(body: string): {
+  body: string;
+  demos: DemoLinkSpec[];
+} {
+  const blocks = body.split(/\n{2,}/);
+  let firstDemo = blocks.length;
+  const demos: DemoLinkSpec[] = [];
+  for (let index = blocks.length - 1; index >= 0; index--) {
+    const link = parseSingleLink(blocks[index] ?? '');
+    if (!link?.href.startsWith('/')) break;
+    demos.unshift(link);
+    firstDemo = index;
+  }
+  return { body: blocks.slice(0, firstDemo).join('\n\n').trim(), demos };
+}
+
+/**
+ * The displayed form of a demo link label: the `Demo:` prefix an author writes
+ * to mark the paragraph is dropped, and the first character is uppercased.
+ * @param label - The raw link label.
+ * @returns What the button shows.
+ */
+export function demoLabel(label: string): string {
+  const text = label.replace(DEMO_PREFIX, '');
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}
+
+const DEMO_PREFIX = /^Demo:\s*/i;

package/src/slides/core/index.ts

@@ -0,0 +1,22 @@
+export type { DemoLinkSpec } from './demoLinks.ts';
+export { demoLabel, parseSingleLink, splitDemoLinks } from './demoLinks.ts';
+export type { SectionHeading } from './sectionHeading.ts';
+export { parseSectionHeading } from './sectionHeading.ts';
+export type { SlideAction } from './slideNavigation.ts';
+export { clampSlideIndex, slideActionForKey } from './slideNavigation.ts';
+export type { Slide, Talk, TalkMeta } from './talk.ts';
+export { parseTalk } from './talk.ts';
+export type { TalkManifest, TalkSummary } from './talkManifest.ts';
+export {
+  buildTalkManifest,
+  parseTalkManifest,
+  talkSourceUrl,
+  talkSummary,
+} from './talkManifest.ts';
+export type { TalkOrigin } from './talkOrigin.ts';
+export {
+  TALK_ORIGIN_PARAM,
+  formatTalkOrigin,
+  parseTalkOrigin,
+  withTalkOrigin,
+} from './talkOrigin.ts';

package/src/slides/core/sectionHeading.ts

@@ -0,0 +1,29 @@
+/** The parts of a section divider's heading. */
+export interface SectionHeading {
+  /** The section number, as written; empty when the heading carries none. */
+  number: string;
+  /** The section title, without its number; empty when the heading carries none. */
+  title: string;
+  /** Whatever the body holds besides that heading. */
+  rest: string;
+}
+
+/**
+ * Split a section-divider body into its leading number, its title and the rest
+ * of the Markdown, so a template can set the number apart from the title.
+ * `·`, `.`, `:`, `—` and `-` all separate the two.
+ * @param body - Markdown body, normally starting with `# N · Title`.
+ * @returns The parsed heading; a body with no numbered heading keeps all of
+ *   itself in `rest`, leaving `number` and `title` empty.
+ */
+export function parseSectionHeading(body: string): SectionHeading {
+  const match = HEAD_RE.exec(body);
+  const number = match?.groups?.number;
+  const title = match?.groups?.title;
+  if (match === null || number === undefined || title === undefined) {
+    return { number: '', title: '', rest: body.trim() };
+  }
+  return { number, title, rest: body.replace(match[0], '').trim() };
+}
+
+const HEAD_RE = /^#\s+(?<number>\d+)\s*[.:·—-]\s*(?<title>.+?)\s*$/m;

package/src/slides/core/slideNavigation.ts

@@ -0,0 +1,77 @@
+/**
+ * What a key does during a presentation, decided without a DOM.
+ *
+ * The current slide lives in the address, so it arrives as whatever a link
+ * carried — a missing number, a negative one, one past the end of a talk that
+ * has since been shortened. Every move is therefore clamped here rather than
+ * trusted, and the player only ever renders a slide that exists.
+ */
+
+/**
+ * The slide a requested index resolves to.
+ * @param index - The index asked for, from a link or a keystroke.
+ * @param total - How many slides the talk holds.
+ * @returns A zero-based index that exists, or `0` for a talk with no slides.
+ */
+export function clampSlideIndex(index: number, total: number): number {
+  if (!Number.isFinite(total) || total < 1) return 0;
+  if (Number.isNaN(index) || index < 0) return 0;
+  const last = total - 1;
+  return index > last ? last : Math.trunc(index);
+}
+
+/** What a key press asks the player to do. */
+export type SlideAction =
+  | { kind: 'go'; index: number }
+  | { kind: 'blank'; color: 'black' | 'white' }
+  | { kind: 'fullscreen' }
+  | { kind: 'notes' }
+  | null;
+
+/**
+ * The action a key press means, with every move already clamped: stepping past
+ * the last slide, or back from the first, stays on the slide it is on rather
+ * than leaving the talk.
+ * @param key - The `key` of the keyboard event.
+ * @param index - Which slide is showing.
+ * @param total - How many slides the talk holds.
+ * @returns The action, or `null` when the key means nothing here.
+ */
+export function slideActionForKey(
+  key: string,
+  index: number,
+  total: number,
+): SlideAction {
+  switch (key) {
+    case 'ArrowRight':
+    case 'ArrowDown':
+    case 'PageDown':
+    case ' ':
+      return { kind: 'go', index: clampSlideIndex(index + 1, total) };
+    case 'ArrowLeft':
+    case 'ArrowUp':
+    case 'PageUp':
+      return { kind: 'go', index: clampSlideIndex(index - 1, total) };
+    case 'Home':
+      return { kind: 'go', index: 0 };
+    case 'End':
+      return { kind: 'go', index: clampSlideIndex(total - 1, total) };
+    default:
+      return letterAction(key);
+  }
+}
+
+function letterAction(key: string): SlideAction {
+  switch (key.toLowerCase()) {
+    case 'f':
+      return { kind: 'fullscreen' };
+    case 'b':
+      return { kind: 'blank', color: 'black' };
+    case 'w':
+      return { kind: 'blank', color: 'white' };
+    case 'n':
+      return { kind: 'notes' };
+    default:
+      return null;
+  }
+}