react-cheminfo 0.8.0 → 0.10.0

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;

package/src/slides/core/talkManifest.ts

@@ -0,0 +1,158 @@
+import type { Talk } from './talk.ts';
+
+/**
+ * How one site publishes its talks so another can list them.
+ *
+ * The talks themselves are Markdown files served by the site that gave them;
+ * a manifest is the small JSON index a sibling site fetches to show them
+ * without holding a copy. It is read tolerantly, because the site fetching it
+ * has no control over the version of the file it gets.
+ */
+
+/** One talk, as a listing shows it. */
+export interface TalkSummary {
+  /** How the publishing site names the talk in its addresses. */
+  id: string;
+  /** The talk title. */
+  title: string;
+  /**
+   * A second line under the title.
+   * @default undefined
+   */
+  subtitle?: string;
+  /**
+   * Conference or event it was given at.
+   * @default undefined
+   */
+  event?: string;
+  /**
+   * When it was given, as an ISO date (`YYYY-MM-DD`).
+   * @default undefined
+   */
+  date?: string;
+  /**
+   * Who presented it.
+   * @default undefined
+   */
+  author?: string;
+  /** How many slides it holds. */
+  slideCount: number;
+}
+
+/** Every talk one site publishes. */
+export interface TalkManifest {
+  /** The `ECOSYSTEM_SITES` id of the site that gave the talks. */
+  site: string;
+  /** Where that site is served from, as `https://host`. */
+  origin: string;
+  /** The talks, in the order the site lists them. */
+  talks: TalkSummary[];
+}
+
+/**
+ * The listing entry for one parsed talk.
+ * @param id - How the site names the talk in its addresses.
+ * @param talk - The parsed talk.
+ * @returns Its summary, carrying only the metadata a listing shows.
+ */
+export function talkSummary(id: string, talk: Talk): TalkSummary {
+  const summary: TalkSummary = {
+    id,
+    title: talk.meta.title,
+    slideCount: talk.slides.length,
+  };
+  if (talk.meta.subtitle !== undefined) summary.subtitle = talk.meta.subtitle;
+  if (talk.meta.event !== undefined) summary.event = talk.meta.event;
+  if (talk.meta.date !== undefined) summary.date = talk.meta.date;
+  if (talk.meta.author !== undefined) summary.author = talk.meta.author;
+  return summary;
+}
+
+/**
+ * Build the manifest a site publishes.
+ * @param input - The site, where it is served from, and its parsed talks.
+ * @param input.site - The `ECOSYSTEM_SITES` id of the publishing site.
+ * @param input.origin - Where that site is served from, as `https://host`.
+ * @param input.talks - The talks, each with the id the site names it by.
+ * @returns The manifest, ready to be written as JSON.
+ */
+export function buildTalkManifest(input: {
+  /** The `ECOSYSTEM_SITES` id of the publishing site. */
+  site: string;
+  /** Where that site is served from, as `https://host`. */
+  origin: string;
+  /** The talks, each with the id the site names it by. */
+  talks: ReadonlyArray<{ id: string } & Talk>;
+}): TalkManifest {
+  const talks: TalkSummary[] = [];
+  for (const talk of input.talks) {
+    talks.push(talkSummary(talk.id, talk));
+  }
+  return { site: input.site, origin: input.origin, talks };
+}
+
+/**
+ * Read a manifest a sibling site published.
+ *
+ * Unknown keys are ignored and an entry missing what a listing needs is
+ * dropped, so a site running an older or newer version of the format still
+ * lists whatever it can understand instead of showing nothing.
+ * @param value - The parsed JSON, of unknown shape.
+ * @returns The manifest, or `null` when the value is not one.
+ */
+export function parseTalkManifest(value: unknown): TalkManifest | null {
+  if (typeof value !== 'object' || value === null) return null;
+  const record = value as Record<string, unknown>;
+  const site = text(record.site);
+  const origin = text(record.origin);
+  if (site === undefined || origin === undefined) return null;
+  if (!Array.isArray(record.talks)) return null;
+  const talks: TalkSummary[] = [];
+  for (const entry of record.talks) {
+    const summary = parseSummary(entry);
+    if (summary !== null) talks.push(summary);
+  }
+  return { site, origin, talks };
+}
+
+/**
+ * Where the Markdown source of one talk of a manifest is served.
+ * @param manifest - The manifest naming the publishing site.
+ * @param id - Which talk.
+ * @returns The absolute URL of the talk source.
+ */
+export function talkSourceUrl(manifest: TalkManifest, id: string): string {
+  return `${manifest.origin.replace(TRAILING_SLASHES, '')}/talks/${id}.md`;
+}
+
+function parseSummary(value: unknown): TalkSummary | null {
+  if (typeof value !== 'object' || value === null) return null;
+  const record = value as Record<string, unknown>;
+  const id = text(record.id);
+  const title = text(record.title);
+  const slideCount = record.slideCount;
+  if (id === undefined || title === undefined) return null;
+  if (typeof slideCount !== 'number' || !Number.isFinite(slideCount)) {
+    return null;
+  }
+  const summary: TalkSummary = {
+    id,
+    title,
+    slideCount: Math.max(Math.trunc(slideCount), 0),
+  };
+  const subtitle = text(record.subtitle);
+  const event = text(record.event);
+  const date = text(record.date);
+  const author = text(record.author);
+  if (subtitle !== undefined) summary.subtitle = subtitle;
+  if (event !== undefined) summary.event = event;
+  if (date !== undefined) summary.date = date;
+  if (author !== undefined) summary.author = author;
+  return summary;
+}
+
+function text(value: unknown): string | undefined {
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+const TRAILING_SLASHES = /\/+$/;

package/src/slides/core/talkOrigin.ts

@@ -0,0 +1,83 @@
+import { firstValues, parseQuery } from '../../share/core/query.ts';
+
+/**
+ * The round trip from a slide to a live demo and back.
+ *
+ * A demo link opens the real tool, so the presenter is then on an ordinary page
+ * of an ordinary site with no way back to the talk. One query parameter carries
+ * where they came from, which is enough for that page to offer the way back —
+ * and, because the site the talk lives on may not be the site the demo runs on,
+ * the parameter names both.
+ */
+
+/** The query parameter a demo link carries its origin in. */
+export const TALK_ORIGIN_PARAM = 'from';
+
+/** Where a demo was opened from. */
+export interface TalkOrigin {
+  /** Which talk, as the publishing site names it. */
+  talkId: string;
+  /** Which slide of it, zero-based. */
+  slide: number;
+  /**
+   * The `ECOSYSTEM_SITES` id of the site the talk is published by, for a demo
+   * that runs on a different site than the talk.
+   * @default undefined — the talk lives on the site the demo runs on
+   */
+  site?: string;
+}
+
+/**
+ * Write an origin as the value of the `from` parameter.
+ * @param origin - Which talk and slide the demo was opened from.
+ * @returns `talk:<site>:<id>:<slide>`, or `talk:<id>:<slide>` when the talk
+ *   lives on the site the link points at.
+ */
+export function formatTalkOrigin(origin: TalkOrigin): string {
+  const slide = Math.max(Math.trunc(origin.slide), 0);
+  const site = origin.site === undefined ? '' : `${origin.site}:`;
+  return `talk:${site}${origin.talkId}:${slide}`;
+}
+
+/**
+ * Read the origin out of an address's query string.
+ *
+ * Anything malformed reads as no origin at all: a link retyped from a slide, or
+ * one written before the talk was renamed, must still open the tool it points
+ * at rather than fail on its way in.
+ * @param search - The query string, with or without its leading `?`.
+ * @returns The origin, or `null` when the address carries none.
+ */
+export function parseTalkOrigin(search: string): TalkOrigin | null {
+  const value = firstValues(parseQuery(search)).get(TALK_ORIGIN_PARAM);
+  if (value === undefined) return null;
+  const match = ORIGIN_RE.exec(value);
+  const talkId = match?.groups?.talkId;
+  const slide = Number.parseInt(match?.groups?.slide ?? '', 10);
+  if (talkId === undefined || !Number.isFinite(slide)) return null;
+  const site = match?.groups?.site;
+  return site === undefined ? { talkId, slide } : { talkId, slide, site };
+}
+
+/**
+ * Point a demo link at its target, carrying where it was opened from.
+ * @param href - The target, relative or absolute, with or without a query.
+ * @param origin - Which talk and slide the link sits on.
+ * @returns The same address with the `from` parameter added, its own
+ *   parameters and its fragment untouched.
+ */
+export function withTalkOrigin(href: string, origin: TalkOrigin): string {
+  const cut = href.indexOf('#');
+  const address = cut === -1 ? href : href.slice(0, cut);
+  const fragment = cut === -1 ? '' : href.slice(cut);
+  const separator = address.includes('?') ? '&' : '?';
+  // A colon reads as a colon in these links, and parses back identically.
+  const value = encodeURIComponent(formatTalkOrigin(origin)).replaceAll(
+    '%3A',
+    ':',
+  );
+  return `${address}${separator}${TALK_ORIGIN_PARAM}=${value}${fragment}`;
+}
+
+const ORIGIN_RE =
+  /^talk:(?:(?<site>[\da-z-]+):)?(?<talkId>[^:]+):(?<slide>\d+)$/i;

package/src/slides/ui/BackToSlides.tsx

@@ -0,0 +1,49 @@
+import { Icon } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import { isModifiedClick } from '../../chrome/ui/navItem.ts';
+import type { TalkOrigin } from '../core/index.ts';
+
+/** Where the visitor came from, and how to send them back. */
+export interface BackToSlidesProps {
+  /** The talk and slide a demo link was opened from, or `null` for none. */
+  origin: TalkOrigin | null;
+  /** The address of that slide. */
+  href: string;
+  /**
+   * What the site does when the pill is clicked, for a site that routes in the
+   * browser. A modified click is left to the browser either way.
+   * @default undefined — the browser follows the address
+   */
+  onReturn?: () => void;
+}
+
+/**
+ * The way back to the slide a demo was opened from.
+ *
+ * A demo link drops the presenter on an ordinary page of an ordinary site, so
+ * during a talk the site stays fully browsable and the talk stays one click
+ * away. It renders nothing at all when the page was not reached from a slide.
+ * @param props - See {@link BackToSlidesProps}.
+ * @returns The pill, or nothing.
+ */
+export function BackToSlides(props: BackToSlidesProps): ReactElement | null {
+  const { origin, href, onReturn } = props;
+  if (origin === null) return null;
+
+  return (
+    <a
+      className="back-to-slides no-print"
+      href={href}
+      title={`Back to slide ${origin.slide + 1}`}
+      onClick={(event) => {
+        if (onReturn === undefined || isModifiedClick(event)) return;
+        event.preventDefault();
+        onReturn();
+      }}
+    >
+      <Icon icon="presentation" size={14} />
+      Back to slides
+    </a>
+  );
+}

package/src/slides/ui/DemoLink.tsx

@@ -0,0 +1,67 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import type { TalkOrigin } from '../core/index.ts';
+import { withTalkOrigin } from '../core/index.ts';
+
+/**
+ * How a site draws a link that leaves a slide for one of its own pages.
+ *
+ * The player never navigates: a site that routes in the browser passes its own
+ * link here, and the address it is given already carries the slide it was
+ * opened from. The children arrive already wrapped in the deck's arrow and
+ * label spans, so a site's element only has to carry `slide-demo` for the
+ * styling to apply.
+ */
+export type RenderSlideLink = (link: {
+  /** The address the link opens, `from` parameter included. */
+  href: string;
+  /** What the link reads. */
+  children: ReactNode;
+}) => ReactElement;
+
+/** What a demo link points at, and how it is drawn. */
+export interface DemoLinkProps {
+  /** The in-app route the demo opens, as the slide wrote it. */
+  href: string;
+  /**
+   * Which slide the link sits on, added to the address so the tool it opens can
+   * offer the way back. Nothing is added when it is left out.
+   * @default undefined
+   */
+  origin?: TalkOrigin;
+  /**
+   * The site's own link, for a site that routes in the browser.
+   * @default undefined — a plain anchor
+   */
+  renderLink?: RenderSlideLink;
+  /** The link label. */
+  children: ReactNode;
+}
+
+/**
+ * A link from a slide into the live tool it demonstrates.
+ * @param props - See {@link DemoLinkProps}.
+ * @returns The link.
+ */
+export function DemoLink(props: DemoLinkProps): ReactElement {
+  const { href, origin, renderLink, children } = props;
+  const address = origin === undefined ? href : withTalkOrigin(href, origin);
+  const label = (
+    <>
+      <span className="slide-demo-arrow" aria-hidden="true">
+        ▸
+      </span>
+      <span className="slide-demo-label">{children}</span>
+    </>
+  );
+
+  if (renderLink !== undefined) {
+    return renderLink({ href: address, children: label });
+  }
+
+  return (
+    <a className="slide-demo" href={address}>
+      {label}
+    </a>
+  );
+}

package/src/slides/ui/EmbedSlide.tsx

@@ -0,0 +1,85 @@
+import type { ReactElement } from 'react';
+
+import type { Slide } from '../core/talk.ts';
+
+import { SlideBody } from './SlideBody.tsx';
+
+/** What an embedded slide draws. */
+export interface EmbedSlideProps {
+  /** The slide, whose body holds the prose and, on its own line, the address. */
+  slide: Slide;
+}
+
+/**
+ * A slide that is the tool itself, running.
+ *
+ * Every tool of the family takes `?embed`, so a lecture can show the real thing
+ * instead of a screenshot of it — which is also the only version of the slide
+ * that stays true after the tool is improved. The heading and any prose stay
+ * above the frame; the last bare URL of the body is what is framed.
+ * @param props - See {@link EmbedSlideProps}.
+ * @returns The slide.
+ */
+export function EmbedSlide(props: EmbedSlideProps): ReactElement {
+  const { slide } = props;
+  const { prose, src } = splitEmbedAddress(slide.body);
+
+  return (
+    <div className="slide slide--embed">
+      <div className="slide-content">
+        {prose === '' ? null : <SlideBody body={prose} />}
+        {src === null ? (
+          <p className="slide-embed-missing">
+            This slide frames a tool, but carries no address.
+          </p>
+        ) : (
+          <iframe
+            className="slide-embed-frame"
+            src={src}
+            title={frameTitle(src)}
+            allow="clipboard-write; fullscreen"
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The prose and the address of an embedded slide.
+ *
+ * The address is written as a bare URL on its own line, because a teacher
+ * pastes what the tool's Share dialog gave them and nothing else.
+ * @param body - The slide body.
+ * @returns The prose without the address, and the address.
+ */
+function splitEmbedAddress(body: string): {
+  prose: string;
+  src: string | null;
+} {
+  const lines = body.split('\n');
+  for (let index = lines.length - 1; index >= 0; index--) {
+    const line = (lines[index] ?? '').trim();
+    if (line === '') continue;
+    if (!line.startsWith('http://') && !line.startsWith('https://')) break;
+    if (line.includes(' ')) break;
+    const prose = [...lines.slice(0, index), ...lines.slice(index + 1)]
+      .join('\n')
+      .trim();
+    return { prose, src: line };
+  }
+  return { prose: body.trim(), src: null };
+}
+
+/**
+ * A frame without a title is unreadable to a screen reader.
+ * @param src - The address being framed.
+ * @returns What the frame is called.
+ */
+function frameTitle(src: string): string {
+  try {
+    return `${new URL(src).hostname}, embedded`;
+  } catch {
+    return 'Embedded tool';
+  }
+}

package/src/slides/ui/SectionSlide.tsx

@@ -0,0 +1,44 @@
+import type { ReactElement } from 'react';
+
+import { parseSectionHeading } from '../core/index.ts';
+
+import { SlideBody } from './SlideBody.tsx';
+
+/** The body of a section divider. */
+export interface SectionSlideProps {
+  /** The Markdown body, normally starting with `# N · Title`. */
+  body: string;
+}
+
+/**
+ * The slide that says a new part of the talk starts here: the section number
+ * set huge and near-transparent, with the title, an accent rule and whatever
+ * else the body holds stacked beside it.
+ *
+ * The numeral is decoration, not text — the heading beside it already says
+ * where the talk is — so it is hidden from a screen reader.
+ * @param props - See {@link SectionSlideProps}.
+ * @returns The divider slide.
+ */
+export function SectionSlide(props: SectionSlideProps): ReactElement {
+  const { number, title, rest } = parseSectionHeading(props.body);
+
+  return (
+    <div className="slide slide--section">
+      <div className="section-slide">
+        <div className="section-number" aria-hidden="true">
+          {number}
+        </div>
+        <div className="section-body">
+          {title === '' ? null : <h1 className="section-title">{title}</h1>}
+          <hr className="section-rule" />
+          {rest === '' ? null : (
+            <div className="section-sub">
+              <SlideBody body={rest} />
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}