react-cheminfo 0.7.0 → 0.9.0

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

package/src/slides/ui/Slide.tsx

@@ -0,0 +1,143 @@
+import type { ComponentType, ReactElement } from 'react';
+import { Fragment } from 'react';
+
+import type {
+  Slide as SlideData,
+  TalkMeta,
+  TalkOrigin,
+} from '../core/index.ts';
+import { demoLabel, splitDemoLinks } from '../core/index.ts';
+
+import type { RenderSlideLink } from './DemoLink.tsx';
+import { DemoLink } from './DemoLink.tsx';
+import { EmbedSlide } from './EmbedSlide.tsx';
+import { SectionSlide } from './SectionSlide.tsx';
+import { SlideBody } from './SlideBody.tsx';
+
+/** What every layout — the generic ones and a site's own — is handed. */
+export interface SlideLayoutProps {
+  /** The slide to draw. */
+  slide: SlideData;
+  /** How the publishing site names the talk in its addresses. */
+  talkId: string;
+  /** Which slide of the talk this is, zero-based. */
+  slideIndex: number;
+  /**
+   * Which site published the deck, written into the way back.
+   * @default undefined — the site playing it
+   */
+  site?: string;
+  /**
+   * Where the publishing site lives, which a relative address in the deck is
+   * resolved against.
+   * @default undefined — the addresses are this site's own
+   */
+  talkOrigin?: string;
+  /** What the talk's front-matter said, for a layout that draws from it. */
+  meta: TalkMeta;
+  /**
+   * The site's own link, used for the in-app links of the slide.
+   * @default undefined — a plain anchor
+   */
+  renderLink?: RenderSlideLink;
+}
+
+/** A slide, and the layouts available to draw it. */
+export interface SlideViewProps extends SlideLayoutProps {
+  /**
+   * The layouts this site adds, by the name a slide writes in its
+   * `<!-- layout: … -->` marker. An entry here also replaces a generic layout
+   * of the same name.
+   * @default undefined
+   */
+  layouts?: Record<string, ComponentType<SlideLayoutProps>>;
+}
+
+/**
+ * Draw one slide with the layout it asks for.
+ *
+ * The layout name is not a closed list — a deck is written before the site
+ * knows how to draw it — so a name neither the site nor the player recognises
+ * falls back to the plain content layout. A talk must never fail to open
+ * because one of its slides asks for something that is not there yet.
+ * @param props - See {@link SlideViewProps}.
+ * @returns The slide.
+ */
+export function SlideView(props: SlideViewProps): ReactElement {
+  const { layouts, ...layoutProps } = props;
+  const { slide } = layoutProps;
+
+  const Custom = layouts?.[slide.layout];
+  if (Custom !== undefined) return <Custom {...layoutProps} />;
+  if (slide.layout === 'section') return <SectionSlide body={slide.body} />;
+  if (slide.layout === 'embed') return <EmbedSlide slide={slide} />;
+
+  return <GenericSlide {...layoutProps} />;
+}
+
+/** The layouts the player draws itself, for any deck on any site. */
+const GENERIC_LAYOUTS = new Set(['content', 'title', 'quote', 'thanks']);
+
+function GenericSlide(props: SlideLayoutProps): ReactElement {
+  const { slide, talkId, slideIndex, meta, renderLink, site, talkOrigin } =
+    props;
+  const layout = GENERIC_LAYOUTS.has(slide.layout) ? slide.layout : 'content';
+  const { body, demos } = splitDemoLinks(slide.body);
+  const origin: TalkOrigin =
+    site === undefined
+      ? { talkId, slide: slideIndex }
+      : { talkId, slide: slideIndex, site };
+  const logos = layout === 'title' ? (meta.logos ?? []) : [];
+
+  return (
+    <div className={`slide slide--${layout}`}>
+      <div className="slide-content">
+        <SlideBody body={body} origin={origin} renderLink={renderLink} />
+        {logos.length === 0 ? null : (
+          <div className="slide-logos">
+            {logos.map((logo) => (
+              <img key={logo} className="slide-logo" src={logo} alt="" />
+            ))}
+          </div>
+        )}
+        {demos.length === 0 ? null : (
+          <div className="slide-demos">
+            <span className="slide-demos-label">Live demos:</span>
+            {demos.map((demo, index) => (
+              <Fragment key={demo.href}>
+                {index === 0 ? null : (
+                  <span className="slide-demos-separator" aria-hidden="true">
+                    |
+                  </span>
+                )}
+                <DemoLink
+                  href={resolveDemoHref(demo.href, talkOrigin)}
+                  origin={origin}
+                  renderLink={renderLink}
+                >
+                  {demoLabel(demo.label)}
+                </DemoLink>
+              </Fragment>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Where a demo link actually points.
+ *
+ * A deck writes `/mf-finder?mass=300`, meaning its own site. Played there it is
+ * exactly that; played on another site of the family it has to be resolved
+ * against the site that wrote it, or the link lands on a page that does not
+ * exist.
+ * @param href - The address the slide wrote.
+ * @param talkOrigin - Where the publishing site lives, when it is not this one.
+ * @returns The address to open.
+ */
+function resolveDemoHref(href: string, talkOrigin?: string): string {
+  if (talkOrigin === undefined || !href.startsWith('/')) return href;
+  return `${talkOrigin.replace(/\/$/, '')}${href}`;
+}

package/src/slides/ui/SlideBody.tsx

@@ -0,0 +1,64 @@
+import type { ReactElement } from 'react';
+import Markdown from 'react-markdown';
+import rehypeRaw from 'rehype-raw';
+
+import type { TalkOrigin } from '../core/index.ts';
+
+import type { RenderSlideLink } from './DemoLink.tsx';
+import { DemoLink } from './DemoLink.tsx';
+
+/** The Markdown of a slide, and where its links go. */
+export interface SlideBodyProps {
+  /** The Markdown source of the slide, or of one part of it. */
+  body: string;
+  /**
+   * Which slide the body belongs to, carried by every in-app link it holds so
+   * the tool a demo opens can offer the way back.
+   * @default undefined
+   */
+  origin?: TalkOrigin;
+  /**
+   * The site's own link, used for the in-app links of the body.
+   * @default undefined — a plain anchor
+   */
+  renderLink?: RenderSlideLink;
+}
+
+/**
+ * Render a slide's Markdown.
+ *
+ * A talk is written as prose, so raw HTML in the source is kept: a slide
+ * routinely holds a `<sub>`, a `<br>` or a figure the Markdown syntax cannot
+ * express. A link to an in-app route becomes a demo link; every other link
+ * leaves the deck in a tab of its own, so a click during a talk never loses the
+ * slide it was made from.
+ * @param props - See {@link SlideBodyProps}.
+ * @returns The rendered body.
+ */
+export function SlideBody(props: SlideBodyProps): ReactElement {
+  const { body, origin, renderLink } = props;
+
+  return (
+    <Markdown
+      rehypePlugins={[rehypeRaw]}
+      components={{
+        a({ href, children }) {
+          if (href?.startsWith('/') === true) {
+            return (
+              <DemoLink href={href} origin={origin} renderLink={renderLink}>
+                {children}
+              </DemoLink>
+            );
+          }
+          return (
+            <a href={href} target="_blank" rel="noreferrer">
+              {children}
+            </a>
+          );
+        },
+      }}
+    >
+      {body}
+    </Markdown>
+  );
+}