react-cheminfo 0.8.0 → 0.9.0

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

package/src/slides/ui/Slideshow.tsx

@@ -0,0 +1,282 @@
+import type {
+  CSSProperties,
+  ComponentType,
+  MouseEvent,
+  ReactElement,
+} from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { useContainerSize } from '../../hooks/ui/useContainerSize.ts';
+import type { Talk } from '../core/index.ts';
+import { clampSlideIndex, slideActionForKey } from '../core/index.ts';
+
+import type { RenderSlideLink } from './DemoLink.tsx';
+import type { SlideLayoutProps } from './Slide.tsx';
+import { SlideView } from './Slide.tsx';
+import { SlideshowBar } from './SlideshowBar.tsx';
+
+/** The talk being presented, and everything the site keeps a hand on. */
+export interface SlideshowProps {
+  /** The parsed talk. */
+  talk: Talk;
+  /** Which slide is showing, zero-based; clamped into the talk before drawing. */
+  index: number;
+  /** Called with the slide to show; the site writes it wherever it keeps it. */
+  onIndex: (index: number) => void;
+  /**
+   * Called when the presenter leaves the talk. The bar carries no Exit button
+   * when it is left out.
+   * @default undefined
+   */
+  onExit?: () => void;
+  /**
+   * The layouts this site adds, by the name a slide writes in its
+   * `<!-- layout: … -->` marker.
+   * @default undefined
+   */
+  layouts?: Record<string, ComponentType<SlideLayoutProps>>;
+  /**
+   * The site's own link, used for the in-app links the slides hold.
+   * @default undefined — a plain anchor
+   */
+  renderLink?: RenderSlideLink;
+  /**
+   * How the publishing site names this talk in its addresses, carried by every
+   * demo link so the tool it opens can offer the way back.
+   * @default '' — the demo links carry no talk
+   */
+  talkId?: string;
+  /**
+   * Which site published the deck. A deck played somewhere else — as
+   * learn.cheminfo.org plays the family's — says so in the way back, so the
+   * link returns to the player it came from rather than to this one.
+   * @default undefined — the deck belongs to the site playing it
+   */
+  site?: string;
+  /**
+   * Where the publishing site lives, e.g. `https://www.chemcalc.org`. A deck
+   * written for one site holds addresses relative to it, so playing it
+   * elsewhere has to resolve them against their own origin rather than against
+   * the page.
+   * @default undefined — the addresses are this site's own
+   */
+  talkOrigin?: string;
+  /**
+   * What the bar reads.
+   * @default the talk's own title
+   */
+  title?: string;
+  /**
+   * Class the player carries, in addition to `slideshow`.
+   * @default undefined
+   */
+  className?: string;
+  /**
+   * Fullscreen owned by the site rather than by the player.
+   *
+   * A deck that links into the live tool wants the whole app fullscreen, not
+   * the player: the player unmounts on the way to the demo, and the browser
+   * would leave fullscreen with it. A site in that shape passes what it
+   * fullscreens and how to toggle it, and the player's key and button drive
+   * that instead of their own element.
+   * @default undefined — the player fullscreens itself
+   */
+  fullscreen?: {
+    /** Whether the site is presenting. */
+    isFullscreen: boolean;
+    /** Called when `f` or the bar's button asks to change that. */
+    onToggle: () => void;
+  };
+}
+
+/** Slides are authored on this canvas, and it is scaled to whatever it is played on. */
+const SLIDE_WIDTH = 1920;
+const SLIDE_HEIGHT = 1080;
+
+/**
+ * The conference player: one talk, one slide at a time, on a canvas scaled to
+ * fill whatever screen it is given.
+ *
+ * The index is controlled, because the site owns the address — the slide lives
+ * in a query parameter so a demo link can return to the exact one — and the
+ * player therefore never touches history itself.
+ *
+ * Arrow keys, space and PageUp/PageDown navigate, `Home` and `End` jump to the
+ * ends, `f` toggles fullscreen, `b` and `w` blank the screen to black and to
+ * white the way a projector remote does, and `n` shows the presenter's notes.
+ * @param props - See {@link SlideshowProps}.
+ * @returns The player.
+ */
+export function Slideshow(props: SlideshowProps): ReactElement {
+  const {
+    talk,
+    index,
+    onIndex,
+    onExit,
+    layouts,
+    renderLink,
+    talkId = '',
+    site,
+    talkOrigin,
+    fullscreen,
+    title,
+    className,
+  } = props;
+
+  const total = talk.slides.length;
+  const current = clampSlideIndex(index, total);
+  const slide = talk.slides[current];
+
+  const playerRef = useRef<HTMLDivElement>(null);
+  const stageRef = useRef<HTMLDivElement>(null);
+  const { width, height } = useContainerSize(stageRef);
+  const scale =
+    width === 0 || height === 0
+      ? 1
+      : Math.min(width / SLIDE_WIDTH, height / SLIDE_HEIGHT);
+
+  const [blank, setBlank] = useState<'black' | 'white' | null>(null);
+  const [showNotes, setShowNotes] = useState(false);
+  const [isFullscreen, setIsFullscreen] = useState(false);
+
+  const goTo = useCallback(
+    (next: number) => {
+      setBlank(null);
+      onIndex(clampSlideIndex(next, total));
+    },
+    [onIndex, total],
+  );
+
+  const ownFullscreen = fullscreen === undefined;
+  const toggleOwn = useCallback(() => {
+    const element = playerRef.current;
+    if (element === null) return;
+    if (document.fullscreenElement === element) {
+      void document.exitFullscreen().catch(() => undefined);
+    } else {
+      void element.requestFullscreen().catch(() => undefined);
+    }
+  }, []);
+  const toggleFullscreen = fullscreen?.onToggle ?? toggleOwn;
+
+  useEffect(() => {
+    if (!ownFullscreen) return;
+    function onFullscreenChange(): void {
+      setIsFullscreen(document.fullscreenElement === playerRef.current);
+    }
+    document.addEventListener('fullscreenchange', onFullscreenChange);
+    return () => {
+      document.removeEventListener('fullscreenchange', onFullscreenChange);
+    };
+  }, [ownFullscreen]);
+
+  useEffect(() => {
+    function onKeyDown(event: KeyboardEvent): void {
+      if (event.metaKey || event.ctrlKey || event.altKey) return;
+      // A player embedded in a page shares the document with its fields, and
+      // space is both "next slide" and a character.
+      if (isTextEntry(event.target)) return;
+      const action = slideActionForKey(event.key, current, total);
+      if (action === null) return;
+      event.preventDefault();
+      switch (action.kind) {
+        case 'go':
+          goTo(action.index);
+          break;
+        case 'blank':
+          setBlank((shown) => (shown === action.color ? null : action.color));
+          break;
+        case 'fullscreen':
+          toggleFullscreen();
+          break;
+        case 'notes':
+          setShowNotes((shown) => !shown);
+          break;
+        default:
+          break;
+      }
+    }
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('keydown', onKeyDown);
+    };
+  }, [current, total, goTo, toggleFullscreen]);
+
+  function onStageClick(event: MouseEvent<HTMLDivElement>): void {
+    // A demo link or a control handles its own click without also stepping on.
+    const target = event.target as Element | null;
+    if (target !== null && target.closest('a, button') !== null) return;
+    goTo(current + 1);
+  }
+
+  const progress = total > 1 ? (current / (total - 1)) * 100 : 100;
+
+  return (
+    <div
+      ref={playerRef}
+      className={
+        className === undefined ? 'slideshow' : `slideshow ${className}`
+      }
+    >
+      {/* Clicking the stage steps on, the way a projector remote does; the
+          keyboard equivalent is the arrow keys the player already listens for. */}
+      <div className="slideshow-stage" ref={stageRef} onClick={onStageClick}>
+        <div className="slide-canvas" style={{ transform: `scale(${scale})` }}>
+          {slide === undefined ? null : (
+            // Keyed on the index so an animated slide replays from its start
+            // every time it is navigated to.
+            <SlideView
+              key={current}
+              slide={slide}
+              talkId={talkId}
+              site={site}
+              talkOrigin={talkOrigin}
+              slideIndex={current}
+              meta={talk.meta}
+              layouts={layouts}
+              renderLink={renderLink}
+            />
+          )}
+        </div>
+        {blank === null ? null : (
+          // Clicking the blank screen brings the slide back, as does pressing
+          // the key that blanked it.
+          <div
+            className={`slideshow-blank slideshow-blank--${blank}`}
+            onClick={(event) => {
+              event.stopPropagation();
+              setBlank(null);
+            }}
+          />
+        )}
+      </div>
+      {showNotes && slide?.notes !== undefined ? (
+        <div className="slideshow-notes no-print">{slide.notes}</div>
+      ) : null}
+      <SlideshowBar
+        title={title ?? talk.meta.title}
+        index={current}
+        total={total}
+        isFullscreen={fullscreen?.isFullscreen ?? isFullscreen}
+        onGo={goTo}
+        onToggleFullscreen={toggleFullscreen}
+        onExit={onExit}
+      />
+      <div
+        className="slideshow-progress"
+        style={{ '--progress': `${progress}%` } as CSSProperties}
+      />
+    </div>
+  );
+}
+
+const TEXT_ENTRY_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
+
+function isTextEntry(target: EventTarget | null): boolean {
+  if (target === null) return false;
+  const element = target as { tagName?: unknown; isContentEditable?: unknown };
+  if (element.isContentEditable === true) return true;
+  return (
+    typeof element.tagName === 'string' && TEXT_ENTRY_TAGS.has(element.tagName)
+  );
+}

package/src/slides/ui/SlideshowBar.tsx

@@ -0,0 +1,83 @@
+import { Button } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+/** Where the talk stands, and what the presenter may do about it. */
+export interface SlideshowBarProps {
+  /** What the bar reads. */
+  title: string;
+  /** Which slide is showing, zero-based. */
+  index: number;
+  /** How many slides the talk holds. */
+  total: number;
+  /** Whether the player is presenting on the whole screen. */
+  isFullscreen: boolean;
+  /** Called with the slide to show. */
+  onGo: (index: number) => void;
+  /** Called to enter or leave fullscreen. */
+  onToggleFullscreen: () => void;
+  /**
+   * Called when the presenter leaves the talk. The bar carries no Exit button
+   * when it is left out.
+   * @default undefined
+   */
+  onExit?: () => void;
+}
+
+/**
+ * The bar under the stage: the way out, the talk's name, and where in it the
+ * presenter stands.
+ *
+ * It is chrome rather than the talk, so it is dropped from a printed handout
+ * along with the rest of the site's.
+ * @param props - See {@link SlideshowBarProps}.
+ * @returns The bar.
+ */
+export function SlideshowBar(props: SlideshowBarProps): ReactElement {
+  const {
+    title,
+    index,
+    total,
+    isFullscreen,
+    onGo,
+    onToggleFullscreen,
+    onExit,
+  } = props;
+
+  return (
+    <div className="slideshow-bar no-print">
+      {onExit === undefined ? null : (
+        <Button variant="minimal" icon="cross" text="Exit" onClick={onExit} />
+      )}
+      <div className="slideshow-title">{title}</div>
+      <div className="slideshow-controls">
+        <Button
+          variant="minimal"
+          icon="chevron-left"
+          aria-label="Previous slide"
+          disabled={index === 0}
+          onClick={() => {
+            onGo(index - 1);
+          }}
+        />
+        <span className="slideshow-counter">
+          {`${total === 0 ? 0 : index + 1} / ${total}`}
+        </span>
+        <Button
+          variant="minimal"
+          icon="chevron-right"
+          aria-label="Next slide"
+          disabled={index >= total - 1}
+          onClick={() => {
+            onGo(index + 1);
+          }}
+        />
+        <Button
+          variant="minimal"
+          icon={isFullscreen ? 'minimize' : 'fullscreen'}
+          aria-label="Toggle fullscreen"
+          onClick={onToggleFullscreen}
+        />
+      </div>
+    </div>
+  );
+}