react-cheminfo 0.7.0 → 0.9.0

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

package/src/slides/ui/TalkList.tsx

@@ -0,0 +1,146 @@
+import type { ReactElement } from 'react';
+
+import { isModifiedClick } from '../../chrome/ui/navItem.ts';
+import { pluralize } from '../../format/core/index.ts';
+import type { TalkManifest, TalkSummary } from '../core/index.ts';
+
+/** The talks to list, and what opening one means. */
+export interface TalkListProps {
+  /** One manifest per publishing site. */
+  manifests: readonly TalkManifest[];
+  /** Called when a talk is picked. */
+  onOpen: (manifest: TalkManifest, talk: TalkSummary) => void;
+  /**
+   * The address a talk sits at, which keeps the card a real link — a middle
+   * click opens a tab of its own, and a crawler walks the list.
+   * @default undefined — the card is a link with no address
+   */
+  renderHref?: (manifest: TalkManifest, talk: TalkSummary) => string;
+  /**
+   * How a site id is written above its talks.
+   * @default the id itself
+   */
+  siteName?: (site: string) => string;
+  /**
+   * What an empty list says. A list that draws nothing at all reads as a
+   * broken page rather than as a site that has published no deck yet.
+   * @default 'No talk yet.'
+   */
+  emptyNote?: string;
+}
+
+/**
+ * The talks on offer: a site's own, or the whole family's.
+ *
+ * The site heading appears only once there is more than one site to tell
+ * apart, so the same component draws a single site's `/talks` page and the
+ * family-wide listing without either looking like the other one's leftovers.
+ * @param props - See {@link TalkListProps}.
+ * @returns The listing.
+ */
+export function TalkList(props: TalkListProps): ReactElement {
+  const {
+    manifests,
+    onOpen,
+    renderHref,
+    siteName,
+    emptyNote = 'No talk yet.',
+  } = props;
+  const groups = groupBySite(manifests);
+  const showSite = groups.length > 1;
+
+  if (groups.length === 0) {
+    return <p className="talk-list-empty">{emptyNote}</p>;
+  }
+
+  return (
+    <div className="talk-list">
+      {groups.map((group) => (
+        <section key={group.site} className="talk-list-group">
+          {showSite ? (
+            <h2 className="talk-list-site">
+              {siteName === undefined ? group.site : siteName(group.site)}
+            </h2>
+          ) : null}
+          <div className="talk-grid">
+            {group.entries.map(({ manifest, talk }) => (
+              <a
+                key={`${manifest.site}:${talk.id}`}
+                className="talk-card"
+                href={renderHref?.(manifest, talk)}
+                onClick={(event) => {
+                  if (isModifiedClick(event)) return;
+                  event.preventDefault();
+                  onOpen(manifest, talk);
+                }}
+              >
+                <div className="talk-card-title">{talk.title}</div>
+                {talk.subtitle === undefined ? null : (
+                  <div className="talk-card-subtitle">{talk.subtitle}</div>
+                )}
+                <div className="talk-card-meta">{occasion(talk)}</div>
+                <div className="talk-card-count">
+                  {`${talk.slideCount} ${pluralize(talk.slideCount, 'slide')}`}
+                </div>
+              </a>
+            ))}
+          </div>
+        </section>
+      ))}
+    </div>
+  );
+}
+
+/** One talk, together with the manifest that published it. */
+interface TalkEntry {
+  /** The manifest the talk was listed in. */
+  manifest: TalkManifest;
+  /** The talk itself. */
+  talk: TalkSummary;
+}
+
+/** Every talk one site published, most recent first. */
+interface TalkGroup {
+  /** The `ECOSYSTEM_SITES` id of the publishing site. */
+  site: string;
+  /** Its talks. */
+  entries: TalkEntry[];
+}
+
+function groupBySite(manifests: readonly TalkManifest[]): TalkGroup[] {
+  const bySite = new Map<string, TalkEntry[]>();
+  for (const manifest of manifests) {
+    let entries = bySite.get(manifest.site);
+    if (entries === undefined) {
+      entries = [];
+      bySite.set(manifest.site, entries);
+    }
+    for (const talk of manifest.talks) entries.push({ manifest, talk });
+  }
+
+  const groups: TalkGroup[] = [];
+  for (const [site, entries] of bySite) {
+    // A site that has published nothing is not a heading over an empty row.
+    if (entries.length === 0) continue;
+    groups.push({ site, entries: entries.toSorted(byMostRecent) });
+  }
+  return groups;
+}
+
+// The dates are ISO, so they order as text; a talk with no date sorts last
+// rather than ahead of every dated one.
+function byMostRecent(left: TalkEntry, right: TalkEntry): number {
+  const before = left.talk.date ?? '';
+  const after = right.talk.date ?? '';
+  if (before === after) return 0;
+  if (before === '') return 1;
+  if (after === '') return -1;
+  return before > after ? -1 : 1;
+}
+
+function occasion(talk: TalkSummary): string {
+  const parts: string[] = [];
+  if (talk.event !== undefined) parts.push(talk.event);
+  if (talk.date !== undefined) parts.push(talk.date);
+  return parts.join(' · ');
+}

package/src/slides/ui/index.ts

@@ -0,0 +1,18 @@
+export type { BackToSlidesProps } from './BackToSlides.tsx';
+export { BackToSlides } from './BackToSlides.tsx';
+export type { DemoLinkProps, RenderSlideLink } from './DemoLink.tsx';
+export { DemoLink } from './DemoLink.tsx';
+export type { EmbedSlideProps } from './EmbedSlide.tsx';
+export { EmbedSlide } from './EmbedSlide.tsx';
+export type { SectionSlideProps } from './SectionSlide.tsx';
+export { SectionSlide } from './SectionSlide.tsx';
+export type { SlideLayoutProps, SlideViewProps } from './Slide.tsx';
+export { SlideView } from './Slide.tsx';
+export type { SlideBodyProps } from './SlideBody.tsx';
+export { SlideBody } from './SlideBody.tsx';
+export type { SlideshowProps } from './Slideshow.tsx';
+export { Slideshow } from './Slideshow.tsx';
+export type { SlideshowBarProps } from './SlideshowBar.tsx';
+export { SlideshowBar } from './SlideshowBar.tsx';
+export type { TalkListProps } from './TalkList.tsx';
+export { TalkList } from './TalkList.tsx';

package/src/slides/vite/index.ts

@@ -0,0 +1,2 @@
+export type { LoadedTalk, TalksOptions } from './talks.ts';
+export { cheminfoTalks, loadTalksFromDisk } from './talks.ts';

package/src/slides/vite/talks.ts

@@ -0,0 +1,126 @@
+/**
+ * Publish a site's talks so another site can list and play them.
+ *
+ * A deck is Markdown in the repository of the site whose subject it teaches,
+ * which is what keeps a talk reviewable. For learn.cheminfo.org to gather the
+ * family's talks it needs two static files per site and no API: a manifest of
+ * what exists, and the source of each deck. Both are written at build time and
+ * served with permissive CORS, because public teaching material is fetched from
+ * a page that is not ours.
+ */
+
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import type { Plugin } from 'vite';
+
+import { siteById, siteUrl } from '../../ecosystem/core/index.ts';
+import type { SiteId } from '../../ecosystem/core/sites.ts';
+import type { Talk } from '../core/talk.ts';
+import { parseTalk } from '../core/talk.ts';
+import { buildTalkManifest } from '../core/talkManifest.ts';
+
+/** What the build needs to know to publish the decks. */
+export interface TalksOptions {
+  /** The site the talks belong to. */
+  site: SiteId;
+  /**
+   * Where the sources live, relative to the project root.
+   * @default 'src/talks'
+   */
+  dir?: string;
+  /**
+   * Where the site is served, used as the manifest's origin.
+   * @default `https://<the site's host>`
+   */
+  origin?: string;
+}
+
+/** One talk on disk: its id, its source, and what the source parses into. */
+export interface LoadedTalk {
+  /** The file name without extension, or the folder name for `<id>/index.md`. */
+  id: string;
+  /** The Markdown as written, which is what other sites fetch. */
+  source: string;
+  /** The parsed talk, for the manifest. */
+  talk: Talk;
+}
+
+/**
+ * Write `talks.json` and `talks/<id>.md` into the build.
+ * @param options - Which site, and where its decks are.
+ * @returns The Vite plugin.
+ */
+export function cheminfoTalks(options: TalksOptions): Plugin {
+  const { site, dir = 'src/talks' } = options;
+  let root = process.cwd();
+  let outDir = 'dist';
+
+  return {
+    name: 'cheminfo-talks',
+    apply: 'build',
+    configResolved(config) {
+      root = config.root;
+      outDir = config.build.outDir;
+    },
+    closeBundle() {
+      const talks = loadTalksFromDisk(join(root, dir));
+      const origin =
+        options.origin ?? siteUrl(siteById(site)).replace(/\/$/, '');
+      const manifest = buildTalkManifest({
+        site,
+        origin,
+        talks: talks.map((entry) => ({ id: entry.id, ...entry.talk })),
+      });
+
+      const target = resolve(root, outDir);
+      mkdirSync(join(target, 'talks'), { recursive: true });
+      writeFileSync(
+        join(target, 'talks.json'),
+        `${JSON.stringify(manifest, null, 2)}\n`,
+      );
+      for (const entry of talks) {
+        writeFileSync(join(target, 'talks', `${entry.id}.md`), entry.source);
+      }
+    },
+  };
+}
+
+/**
+ * Read every deck of a directory, in either of the two shapes a talk takes.
+ * @param directory - Absolute path of the talks directory.
+ * @returns The talks, sorted by id so a build is reproducible.
+ */
+export function loadTalksFromDisk(directory: string): LoadedTalk[] {
+  const loaded: LoadedTalk[] = [];
+  let entries: string[] = [];
+  try {
+    entries = readdirSync(directory);
+  } catch {
+    // A site with no talks yet still builds; it simply publishes an empty list.
+    return loaded;
+  }
+
+  for (const entry of entries) {
+    const path = join(directory, entry);
+    if (entry.endsWith('.md')) {
+      const source = readFileSync(path, 'utf8');
+      loaded.push({
+        id: entry.slice(0, -3),
+        source,
+        talk: parseTalk(source),
+      });
+      continue;
+    }
+    const index = join(path, 'index.md');
+    let source: string;
+    try {
+      source = readFileSync(index, 'utf8');
+    } catch {
+      continue;
+    }
+    loaded.push({ id: entry, source, talk: parseTalk(source) });
+  }
+
+  return loaded.toSorted((left, right) => left.id.localeCompare(right.id));
+}

package/src/slides.ts

@@ -0,0 +1,2 @@
+export * from './slides/core/index.ts';
+export * from './slides/ui/index.ts';

package/src/structure/ui/StructureEditor.tsx

@@ -179,7 +179,7 @@ const ROOT_STYLE: CSSProperties = {
   position: 'relative',
   overflow: 'hidden',
   boxSizing: 'border-box',
-  border: '1px solid #d3d8de',
+  border: '1px solid var(--border, #d3d8de)',
   borderRadius: 6,
   background: '#fff',
 };
@@ -191,6 +191,6 @@ const LOADING_STYLE: CSSProperties = {
   display: 'flex',
   alignItems: 'center',
   justifyContent: 'center',
-  color: '#8a96a3',
+  color: 'var(--text-faint, #8a96a3)',
   fontSize: 13,
 };

package/src/structure/ui/StructurePlaceholder.tsx

@@ -43,6 +43,6 @@ const PLACEHOLDER_STYLE: CSSProperties = {
   display: 'inline-flex',
   alignItems: 'center',
   justifyContent: 'center',
-  color: '#8a96a3',
+  color: 'var(--text-faint, #8a96a3)',
   fontSize: '0.75rem',
 };