react-cheminfo 0.7.0 → 0.9.0

package/src/pedagogy/ui/TutorialStepStrip.tsx

@@ -1,15 +1,29 @@
 import { Button, Tag, Tooltip } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
 
-import type { ExerciseLevel, TutorialStep } from '../core/types.ts';
+import type { ExerciseLevel } from '../core/types.ts';
 
 import { LEVEL_ORDER } from './exerciseMeta.ts';
 import type { TutorialLevelColours } from './tutorialLevels.ts';
 import { TUTORIAL_LEVEL_COLOURS } from './tutorialLevels.ts';
 
+/**
+ * The little a strip needs of a step: what to call it, and which coloured group
+ * it belongs to. A tool passes its own steps, whatever else they carry.
+ */
+export interface TutorialStripStep {
+  /**
+   * What keys the button, when the tool gives its steps one.
+   * @default undefined — the position in the tour keys it instead
+   */
+  id?: string;
+  title: string;
+  level: ExerciseLevel;
+}
+
 export interface TutorialStepStripProps {
   /** The whole tour, in teaching order. */
-  steps: readonly TutorialStep[];
+  steps: readonly TutorialStripStep[];
   /**
    * Which step is open, as its position in `steps`. A position outside the
    * tour is read as one of its ends, so a hand-edited link still opens.
@@ -110,7 +124,7 @@ export function TutorialStepStrip(props: TutorialStepStripProps): ReactElement {
 }
 
 interface LevelStripProps {
-  steps: readonly TutorialStep[];
+  steps: readonly TutorialStripStep[];
   positions: readonly number[];
   colours: TutorialLevelColours;
   label: string;
@@ -122,11 +136,11 @@ function LevelStrip(props: LevelStripProps): ReactElement {
   const { steps, positions, colours, label, activeIndex, onSelect } = props;
   const buttons: ReactNode[] = [];
   for (const position of positions) {
-    const step = steps[position] as TutorialStep;
+    const step = steps[position] as TutorialStripStep;
     const active = position === activeIndex;
     buttons.push(
       <Tooltip
-        key={step.id}
+        key={step.id ?? position}
         content={step.title}
         hoverOpenDelay={HOVER_OPEN_DELAY}
         placement="bottom"
@@ -155,7 +169,7 @@ function LevelStrip(props: LevelStripProps): ReactElement {
 }
 
 function positionsOfLevel(
-  steps: readonly TutorialStep[],
+  steps: readonly TutorialStripStep[],
   level: ExerciseLevel,
 ): number[] {
   const positions: number[] = [];
@@ -172,6 +186,9 @@ function clampIndex(index: number, total: number): number {
 
 /**
  * The open step takes the darker shade of its own level, plus a border.
+ *
+ * Every button is the same square whatever it holds, so the numbers of one
+ * strip stand above those of the next and the tour reads as a grid.
  * @param colours - The two shades of the level the step belongs to.
  * @param active - Whether this is the step on screen.
  * @returns The style of one numbered button.
@@ -181,20 +198,29 @@ function numberStyle(
   active: boolean,
 ): CSSProperties {
   return {
-    background: active ? colours.activeBackground : '#ffffff',
+    display: 'inline-flex',
+    width: STEP_SIZE,
+    height: STEP_SIZE,
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 0,
     border: active ? '2px solid #1c2127' : '1px solid rgb(17 20 24 / 20%)',
     borderRadius: 4,
+    background: active ? colours.activeBackground : '#ffffff',
+    boxSizing: 'border-box',
     color: '#1c2127',
     cursor: 'pointer',
     font: 'inherit',
     fontSize: 12,
+    fontVariantNumeric: 'tabular-nums',
     fontWeight: active ? 700 : 500,
     lineHeight: 1,
-    minWidth: 26,
-    padding: active ? '5px 6px' : '6px 7px',
   };
 }
 
+/** Wide enough for two digits, which every tour of ours stays under a hundred of. */
+const STEP_SIZE = 28;
+
 /** Long enough that the pointer can cross the strip without opening a title. */
 const HOVER_OPEN_DELAY = 150;
 
@@ -227,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/pedagogy/ui/index.ts

@@ -31,7 +31,10 @@ export type {
 export { SyntaxTooltip } from './SyntaxTooltip.tsx';
 export type { TestCaseListProps } from './TestCaseList.tsx';
 export { TestCaseList } from './TestCaseList.tsx';
-export type { TutorialStepStripProps } from './TutorialStepStrip.tsx';
+export type {
+  TutorialStepStripProps,
+  TutorialStripStep,
+} from './TutorialStepStrip.tsx';
 export { TutorialStepStrip } from './TutorialStepStrip.tsx';
 export type { TutorialLevelColours } from './tutorialLevels.ts';
 export { TUTORIAL_LEVEL_COLOURS } from './tutorialLevels.ts';

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

package/src/slides/core/talk.ts

@@ -0,0 +1,203 @@
+/**
+ * The talk format: one Markdown file is one talk, and this reads it.
+ *
+ * A talk is authored as prose rather than as data — an optional front-matter
+ * block, then slides separated by a `---` line. Which template draws a slide is
+ * a comment the author writes, and the name is deliberately not a closed list:
+ * every site registers the layouts it knows how to draw.
+ */
+
+/** Talk-level metadata, read from the front-matter block. */
+export interface TalkMeta {
+  /** Talk title, shown on the title slide and in a talk index. */
+  title: string;
+  /**
+   * A second line under the title.
+   * @default undefined
+   */
+  subtitle?: string;
+  /**
+   * Conference or event the talk was given at.
+   * @default undefined
+   */
+  event?: string;
+  /**
+   * When it was given, as an ISO date (`YYYY-MM-DD`).
+   * @default undefined
+   */
+  date?: string;
+  /**
+   * City or venue.
+   * @default undefined
+   */
+  location?: string;
+  /**
+   * Who presented it.
+   * @default undefined
+   */
+  author?: string;
+  /**
+   * Logo image URLs shown on the title slide, written comma-separated in the
+   * front-matter.
+   * @default undefined
+   */
+  logos?: string[];
+  /**
+   * One sentence about the talk, for a listing or a page description.
+   * @default undefined
+   */
+  description?: string;
+}
+
+/** One slide of a talk. */
+export interface Slide {
+  /**
+   * Which template draws the body. A site maps these names to its own
+   * components, so any lowercase identifier is accepted here.
+   */
+  layout: string;
+  /** The Markdown body, with the layout marker and the notes comment removed. */
+  body: string;
+  /**
+   * What the presenter says over this slide, never drawn on it.
+   * @default undefined
+   */
+  notes?: string;
+}
+
+/** A whole talk: its metadata and its slides, in order. */
+export interface Talk {
+  /** What the front-matter said about the talk. */
+  meta: TalkMeta;
+  /** The slides, in the order they are presented. */
+  slides: Slide[];
+}
+
+/**
+ * Parse a talk written in Markdown into its metadata and its slides.
+ *
+ * The source is read defensively: CRLF endings, a missing front-matter block,
+ * an empty file and a slide holding nothing but whitespace all resolve to
+ * something a player can render rather than to an error.
+ * @param source - The raw Markdown talk source.
+ * @returns The parsed talk; an empty source yields an untitled talk with no slides.
+ */
+export function parseTalk(source: string): Talk {
+  const normalized = source.replaceAll(/\r\n?/g, '\n');
+  const { meta, body } = extractFrontMatter(normalized);
+  const slides: Slide[] = [];
+  for (const chunk of splitSlides(body)) {
+    slides.push(toSlide(chunk));
+  }
+  return { meta, slides };
+}
+
+function extractFrontMatter(source: string): { meta: TalkMeta; body: string } {
+  const lines = source.split('\n');
+  let index = 0;
+  while (index < lines.length && lines[index]?.trim() === '') index++;
+  if (lines[index]?.trim() !== '---') {
+    return { meta: { title: '' }, body: source };
+  }
+  index++;
+  const metaLines: string[] = [];
+  while (index < lines.length && lines[index]?.trim() !== '---') {
+    metaLines.push(lines[index] ?? '');
+    index++;
+  }
+  index++;
+  return { meta: parseMeta(metaLines), body: lines.slice(index).join('\n') };
+}
+
+function parseMeta(metaLines: readonly string[]): TalkMeta {
+  const meta: TalkMeta = { title: '' };
+  for (const line of metaLines) {
+    const match = META_RE.exec(line);
+    const key = match?.groups?.key?.toLowerCase();
+    const value = match?.groups?.value?.trim();
+    if (key === undefined || value === undefined) continue;
+    if (key === 'logos') {
+      meta.logos = splitLogos(value);
+    } else if (TEXT_KEYS.has(key)) {
+      meta[key as TextMetaKey] = value;
+    }
+  }
+  return meta;
+}
+
+function splitLogos(value: string): string[] {
+  const logos: string[] = [];
+  for (const logo of value.split(',')) {
+    const trimmed = logo.trim();
+    if (trimmed !== '') logos.push(trimmed);
+  }
+  return logos;
+}
+
+function splitSlides(body: string): string[] {
+  const chunks: string[][] = [[]];
+  for (const line of body.split('\n')) {
+    if (SEPARATOR_RE.test(line)) {
+      chunks.push([]);
+    } else {
+      chunks.at(-1)?.push(line);
+    }
+  }
+  const slides: string[] = [];
+  for (const chunk of chunks) {
+    const text = chunk.join('\n').trim();
+    if (text !== '') slides.push(text);
+  }
+  return slides;
+}
+
+function toSlide(chunk: string): Slide {
+  const layoutMatch = LAYOUT_RE.exec(chunk);
+  const { body, notes } = extractNotes(chunk.replace(LAYOUT_RE, ''));
+  const layout =
+    layoutMatch?.groups?.layout?.toLowerCase() ?? detectLayout(body);
+  const slide: Slide = { layout, body };
+  if (notes !== '') slide.notes = notes;
+  return slide;
+}
+
+function extractNotes(chunk: string): { body: string; notes: string } {
+  const notes: string[] = [];
+  for (const match of chunk.matchAll(NOTES_RE)) {
+    const text = match.groups?.notes?.trim();
+    if (text !== undefined && text !== '') notes.push(text);
+  }
+  return {
+    body: chunk.replaceAll(NOTES_RE, '').trim(),
+    notes: notes.join('\n\n'),
+  };
+}
+
+function detectLayout(body: string): string {
+  let headings = 0;
+  for (const line of body.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    if (!trimmed.startsWith('#')) return 'content';
+    headings++;
+  }
+  return headings > 0 ? 'title' : 'content';
+}
+
+/** Which keys of {@link TalkMeta} a front-matter line writes as plain text. */
+type TextMetaKey = Exclude<keyof TalkMeta, 'logos'>;
+
+const TEXT_KEYS = new Set<string>([
+  'title',
+  'subtitle',
+  'event',
+  'date',
+  'location',
+  'author',
+  'description',
+]);
+
+const LAYOUT_RE = /<!--\s*layout:\s*(?<layout>[a-z][\da-z-]*)\s*-->/i;
+const NOTES_RE = /<!--\s*notes:\s*(?<notes>.*?)-->/gis;
+const SEPARATOR_RE = /^---[\t ]*$/;
+const META_RE = /^(?<key>[a-z]+)\s*:\s*(?<value>.+)$/i;