react-cheminfo 0.64.1 → 0.65.0

package/src/card/ui/CardDetailsButton.tsx

@@ -0,0 +1,104 @@
+import { Button, Tooltip } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { useEffect } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { pageLocation } from '../../router/core/pageAddress.ts';
+import { useActionTooltip } from '../../shared/ui/useActionTooltip.ts';
+import type { SitePageOptions } from '../core/cardAddress.ts';
+import { sitePageUrl } from '../core/cardAddress.ts';
+
+import {
+  CARD_TOOLTIP_CLASS,
+  CARD_TOOLTIP_DELAY,
+  CARD_TOOLTIP_MODIFIERS,
+} from './cardTooltip.ts';
+import { loadEmbed, loadedEmbed } from './embed.ts';
+
+/** What {@link CardDetailsButton} opens. */
+export interface CardDetailsButtonProps {
+  /**
+   * Writes the address of the page the button opens, when it is pressed.
+   * @default the card's own address without `card`, `embed`, `hide` and
+   *   what `address` says only the card reads — `sitePageUrl` over the page's
+   *   address, the one a sealed link holds in memory included
+   */
+  page?: () => string;
+  /**
+   * How the default page is read off the card's address.
+   * @default {} - `card`, `embed` and `hide` are left out, and nothing else
+   */
+  address?: SitePageOptions;
+  /**
+   * What the tooltip says the button does.
+   * @default the chrome's own line, `Open in a new tab`
+   */
+  tooltip?: string;
+  /**
+   * Value of the `data-testid` attribute of the button.
+   * @default 'card-details'
+   */
+  testId?: string;
+}
+
+/**
+ * The way from a card to the site's own page it stands for, with its chrome,
+ * at the end of the card: a chat keeps the card's top right corner for its own
+ * control. Framed by a chat, the page opens in a new tab, so the conversation
+ * keeps its place; opened on its own, the card becomes the page. It never
+ * prints.
+ * @param props - See {@link CardDetailsButtonProps}.
+ * @returns The button, with the tooltip saying where the page opens.
+ */
+export function CardDetailsButton(props: CardDetailsButtonProps): ReactElement {
+  const { page, address, tooltip, testId = 'card-details' } = props;
+  const t = useChromeT();
+  const { isOpen, target } = useActionTooltip(false, CARD_TOOLTIP_DELAY);
+  useEffect(() => {
+    loadEmbed().catch(() => undefined);
+  }, []);
+  return (
+    <Tooltip
+      content={tooltip ?? t('card.detailsTitle')}
+      placement="top-end"
+      modifiers={CARD_TOOLTIP_MODIFIERS}
+      popoverClassName={CARD_TOOLTIP_CLASS}
+      isOpen={isOpen}
+    >
+      <span className="no-print" style={WRAP_STYLE} {...target}>
+        <Button
+          variant="minimal"
+          size="small"
+          icon="share"
+          text={t('card.details')}
+          aria-label={t('card.detailsLabel')}
+          data-testid={testId}
+          onClick={() => {
+            const url = page === undefined ? cardSitePage(address) : page();
+            const embed = loadedEmbed();
+            if (embed === undefined) {
+              void loadEmbed().then((module) => module.openSitePage(url));
+            } else {
+              embed.openSitePage(url);
+            }
+          }}
+        />
+      </span>
+    </Tooltip>
+  );
+}
+
+/**
+ * The site's page behind the card on screen, read when the button is
+ * pressed: the page's own address — held in memory under a sealed link — on
+ * the origin the card is served from.
+ * @param address - What only the card reads.
+ * @returns The page's absolute address.
+ */
+function cardSitePage(address: SitePageOptions | undefined): string {
+  const { origin } = globalThis.location;
+  const { pathname, search } = pageLocation() ?? globalThis.location;
+  return sitePageUrl({ origin, pathname, search }, address);
+}
+
+const WRAP_STYLE = { display: 'inline-flex' } as const satisfies CSSProperties;

package/src/card/ui/CardFigure.tsx

@@ -0,0 +1,86 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useId } from 'react';
+
+import { FigureDownload } from '../../download/ui/FigureDownload.tsx';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { OverlayLayer } from '../../overlay/ui/OverlayLayer.tsx';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+
+/** What {@link CardFigure} draws and takes away. */
+export interface CardFigureProps {
+  /** The drawing: a chart, a structure, a grid of them. */
+  children: ReactNode;
+  /** What a saved file is called, without its extension. */
+  fileName: string;
+  /**
+   * Glyphs drawn above the one copying the picture: the copy of the data the
+   * figure is drawn from, the notations of its structure
+   * (`StructureExportButton` of `react-cheminfo/structure`).
+   * @default undefined - the picture's glyph alone
+   */
+  tools?: ReactNode;
+  /**
+   * Class of the box the drawing is in, which is what the picture holds.
+   * @default undefined
+   */
+  className?: string;
+  /**
+   * Take the whole width the card gives, as a grid of structures does.
+   * @default false - as wide as the drawing
+   */
+  fill?: boolean;
+  /**
+   * The drawing is HTML rather than one SVG or canvas — a grid of cells — and
+   * the picture saved is painted from it as it is seen.
+   * @default false
+   */
+  html?: boolean;
+  /**
+   * What the picture's glyph is called, for the pointer and a screen reader.
+   * @default the chrome's own line, `Copy or save the picture`
+   */
+  label?: string;
+}
+
+/**
+ * A figure of a card with the glyphs that take it away: the picture copied as
+ * a PNG or saved as a PNG or an SVG, as the chat offers it for its own
+ * figures, and whatever else the figure carries.
+ *
+ * The glyphs stand in a column beside the figure's top right corner rather
+ * than over it, so they hide no part of a curve or an atom, and they fade
+ * until the figure is pointed at or one of them holds the focus: a card shown
+ * in a chat is read far more often than it is copied. `styles/card.css` draws
+ * the column.
+ * @param props - See {@link CardFigureProps}.
+ * @returns The figure, with its column of glyphs.
+ */
+export function CardFigure(props: CardFigureProps): ReactElement {
+  const { children, fileName, tools, className, label } = props;
+  const { fill = false, html = false } = props;
+  const t = useChromeT();
+  const id = useId();
+  return (
+    <div className={joinClassNames('card-figure', fill && 'card-figure--fill')}>
+      <div
+        id={id}
+        className={joinClassNames('card-figure__drawing', className)}
+        data-figure={html ? 'html' : undefined}
+      >
+        {children}
+      </div>
+      {/* Compact: the glyphs of a figure shown in somebody else's page. */}
+      <OverlayLayer density="compact" awake>
+        <div className="card-figure__tools" data-testid="figure-tools">
+          {tools}
+          <FigureDownload
+            targetId={id}
+            fileName={fileName}
+            label={label ?? t('card.copyPicture')}
+            testId="card-save-figure"
+          />
+        </div>
+      </OverlayLayer>
+    </div>
+  );
+}

package/src/card/ui/CardFrame.tsx

@@ -0,0 +1,46 @@
+import type { ReactElement, ReactNode } from 'react';
+
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+
+import { fitCardToFrame } from './fitCardToFrame.ts';
+
+/** What {@link CardFrame} holds. */
+export interface CardFrameProps {
+  /** The card: the answer alone, compactly. */
+  children: ReactNode;
+  /**
+   * Class beside `card`, so a site can reach the card from its stylesheet.
+   * @default undefined
+   */
+  className?: string;
+  /**
+   * Value of the `data-testid` attribute.
+   * @default 'card'
+   */
+  testId?: string;
+}
+
+/**
+ * The page a chat frames inline for one answer: the card, with no header, no
+ * footer and no form, as tall as what it shows. Framed, it reports its height
+ * so the chat fits the frame to it, and grows while a panel it opened is open
+ * so the frame holds that too; opened on its own, it is a page like any other.
+ *
+ * `react-cheminfo/styles/card.css` draws it: no margin on the page around it,
+ * the chat's corner left free by `card__header`, and the row of actions at its
+ * end, `card__end`.
+ * @param props - See {@link CardFrameProps}.
+ * @returns The card's root element.
+ */
+export function CardFrame(props: CardFrameProps): ReactElement {
+  const { children, className, testId = 'card' } = props;
+  return (
+    <div
+      ref={fitCardToFrame}
+      className={joinClassNames('card', className)}
+      data-testid={testId}
+    >
+      {children}
+    </div>
+  );
+}

package/src/card/ui/CopyTableButton.tsx

@@ -0,0 +1,81 @@
+import { Tooltip } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import { CopyButton } from '../../clipboard/ui/CopyButton.tsx';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+
+import {
+  CARD_TOOLTIP_CLASS,
+  CARD_TOOLTIP_DELAY,
+  CARD_TOOLTIP_MODIFIERS,
+} from './cardTooltip.ts';
+
+/** What {@link CopyTableButton} copies. */
+export interface CopyTableButtonProps {
+  /**
+   * Writes the table, tab-separated and header first, when the button is
+   * pressed: a card holding a long table writes nothing until it is asked.
+   */
+  table: () => string;
+  /**
+   * What the tooltip says the button copies, e.g. `Copy the conformers as a
+   * table, to paste into a spreadsheet`.
+   * @default the chrome's own line, `Copy the table, to paste into a
+   *   spreadsheet`
+   */
+  tooltip?: string;
+  /**
+   * Show the glyph alone, which is what a heading of a few letters has room
+   * for. The label is still the button's accessible name.
+   * @default false - the label shows, and gives way to the glyph on a frame
+   *   narrower than 30rem
+   */
+  glyphOnly?: boolean;
+  /**
+   * Value of the `data-testid` attribute of the button's box.
+   * @default 'card-copy-table'
+   */
+  testId?: string;
+}
+
+/**
+ * A card's "Copy as table" action: the table, tab-separated and header first,
+ * which a spreadsheet pastes into its cells. A tick says the clipboard took
+ * it, a cross that the browser refused. It never prints.
+ * @param props - See {@link CopyTableButtonProps}.
+ * @returns The button, with the tooltip saying what it copies.
+ */
+export function CopyTableButton(props: CopyTableButtonProps): ReactElement {
+  const {
+    table,
+    tooltip,
+    glyphOnly = false,
+    testId = 'card-copy-table',
+  } = props;
+  const t = useChromeT();
+  return (
+    <Tooltip
+      content={tooltip ?? t('card.copyTableTitle')}
+      placement="top-end"
+      modifiers={CARD_TOOLTIP_MODIFIERS}
+      popoverClassName={CARD_TOOLTIP_CLASS}
+      hoverOpenDelay={CARD_TOOLTIP_DELAY}
+    >
+      <span data-testid={testId}>
+        <CopyButton
+          content={table}
+          label={t('card.copyTable')}
+          title=""
+          icon="th"
+          minimal
+          small
+          className={joinClassNames(
+            'card__copy-table',
+            glyphOnly && 'card__copy-table--glyph',
+          )}
+        />
+      </span>
+    </Tooltip>
+  );
+}

package/src/card/ui/cardTooltip.ts

@@ -0,0 +1,18 @@
+import type { PopoverProps } from '@blueprintjs/core';
+
+/**
+ * The family's help card, at the width of the few words a card's action
+ * says: `styles/card.css` lets `card-tooltip` shrink to its text.
+ */
+export const CARD_TOOLTIP_CLASS = 'help-tooltip card-tooltip';
+
+/**
+ * Where a card's tooltip goes when the frame has no room above its control:
+ * beside it, rather than cut by the frame's edge.
+ */
+export const CARD_TOOLTIP_MODIFIERS: PopoverProps['modifiers'] = {
+  flip: { options: { fallbackPlacements: ['left'] } },
+};
+
+/** How long the pointer rests on an action of a card before it is named. */
+export const CARD_TOOLTIP_DELAY = 300;

package/src/card/ui/embed.ts

@@ -0,0 +1,27 @@
+import type * as Embed from 'cheminfo-mcp-server/embed';
+
+let loading: Promise<typeof Embed> | undefined;
+let loaded: typeof Embed | undefined;
+
+/**
+ * Load `cheminfo-mcp-server/embed` once, on first use. It is an optional
+ * peer, so `react-cheminfo/card` must import without it; a site that lacks it
+ * gets a card that never talks to a frame.
+ * @returns The module, once loaded.
+ */
+export function loadEmbed(): Promise<typeof Embed> {
+  loading ??= import('cheminfo-mcp-server/embed').then((module) => {
+    loaded = module;
+    return module;
+  });
+  return loading;
+}
+
+/**
+ * The module {@link loadEmbed} loaded, read synchronously — a click must open
+ * its page in the same task, or the browser blocks the new tab.
+ * @returns The module, or undefined while it is still loading.
+ */
+export function loadedEmbed(): typeof Embed | undefined {
+  return loaded;
+}

package/src/card/ui/fitCardToFrame.ts

@@ -0,0 +1,76 @@
+import type * as Embed from 'cheminfo-mcp-server/embed';
+import type { RefObject } from 'react';
+import { useEffect } from 'react';
+
+import { loadEmbed, loadedEmbed } from './embed.ts';
+import { holdRoomForPanels } from './holdRoomForPanels.ts';
+
+/**
+ * Fit the frame a chat shows a card in to the card: report the card's height
+ * to the view framing it, now and on every change, so nothing scrolls twice,
+ * and grow the card while a panel it opened is open, so the frame holds the
+ * panel too. A card opened on its own is the page: there is no frame to tell
+ * and none to grow, and nothing is done.
+ *
+ * Its shape is a React 19 ref callback's — `ref={fitCardToFrame}` — so it
+ * starts once the card is mounted and stops when it is removed. The first
+ * card waits for `cheminfo-mcp-server/embed` to load; a site without it gets
+ * a card that never reports.
+ * @param card - The element holding the whole card; none reports nothing.
+ * @returns A function that stops both, or undefined when nothing started.
+ */
+export function fitCardToFrame(
+  card: HTMLElement | null,
+): (() => void) | undefined {
+  if (card === null) return undefined;
+  const embed = loadedEmbed();
+  if (embed !== undefined) return fitLoaded(embed, card);
+  let stop: (() => void) | undefined;
+  let stopped = false;
+  loadEmbed().then(
+    (module) => {
+      if (!stopped) stop = fitLoaded(module, card);
+    },
+    () => undefined,
+  );
+  return () => {
+    stopped = true;
+    stop?.();
+  };
+}
+
+/**
+ * {@link fitCardToFrame} for a card held in a ref, from its first render to
+ * its last.
+ * @param card - The ref of the element holding the whole card.
+ */
+export function useFitCardToFrame(card: RefObject<HTMLElement | null>): void {
+  useEffect(() => fitCardToFrame(card.current), [card]);
+}
+
+/**
+ * Keep a card at least as tall as the dialogs and popovers opened over it,
+ * framed or not: {@link holdRoomForPanels} for a card held in a ref. A card
+ * whose height is reported elsewhere uses this; one that only needs its frame
+ * fitted uses {@link useFitCardToFrame}, which does both.
+ * @param card - The ref of the element holding the whole card.
+ */
+export function useOverlayRoom(card: RefObject<HTMLElement | null>): void {
+  useEffect(() => {
+    const element = card.current;
+    return element === null ? undefined : holdRoomForPanels(element);
+  }, [card]);
+}
+
+function fitLoaded(
+  embed: typeof Embed,
+  card: HTMLElement,
+): (() => void) | undefined {
+  if (!embed.isFramed()) return undefined;
+  const stopRoom = holdRoomForPanels(card);
+  const stopReport = embed.reportEmbedHeight(card);
+  return () => {
+    stopReport();
+    stopRoom();
+  };
+}

package/src/card/ui/holdRoomForPanels.ts

@@ -0,0 +1,83 @@
+import { roomForPanels } from '../core/panelRoom.ts';
+
+import { anchorBottom, openPanels } from './openPanels.ts';
+
+/**
+ * Keep a card as tall as the dialogs and popovers open over it need, until
+ * the returned function is called; the card gives the height back as each
+ * closes. A chat frames a card exactly as tall as the card reports, so a
+ * panel taller than the card would otherwise be cut at the frame's edge.
+ *
+ * The room is measured once per animation frame, whenever the document
+ * changes — a panel opening, closing or moving changes the tree or a class —
+ * and whenever an open panel changes size, which one whose content arrives
+ * after it opens does without touching the tree. A card whose view fills the
+ * screen holds no room: its frame is not what is on screen then.
+ * @param card - The element whose height the frame follows.
+ * @returns A function that stops watching and gives the card its height back.
+ */
+export function holdRoomForPanels(card: HTMLElement): () => void {
+  let frame = 0;
+  const watched = new Set<Element>();
+  const sizes =
+    typeof ResizeObserver === 'undefined'
+      ? undefined
+      : new ResizeObserver(schedule);
+  const mutations = new MutationObserver(schedule);
+
+  function measure(): void {
+    frame = 0;
+    const panels = openPanels(card);
+    if (sizes !== undefined) watchSizes(sizes, watched, panels.elements);
+    const room = document.fullscreenElement
+      ? 0
+      : roomForPanels(panels.found, anchorBottom(card));
+    const minHeight = room > 0 ? `${room}px` : '';
+    if (card.style.minHeight !== minHeight) card.style.minHeight = minHeight;
+  }
+
+  function schedule(): void {
+    if (frame === 0) frame = requestAnimationFrame(measure);
+  }
+
+  mutations.observe(document.body, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    attributeFilter: ['class'],
+  });
+  document.addEventListener('fullscreenchange', schedule);
+  schedule();
+  return () => {
+    mutations.disconnect();
+    sizes?.disconnect();
+    document.removeEventListener('fullscreenchange', schedule);
+    cancelAnimationFrame(frame);
+    card.style.minHeight = '';
+  };
+}
+
+/**
+ * Watch the size of the panels on screen, and of no other element.
+ * @param sizes - The observer.
+ * @param watched - The elements it watches, kept up to date.
+ * @param panels - The panels open now.
+ */
+function watchSizes(
+  sizes: ResizeObserver,
+  watched: Set<Element>,
+  panels: readonly Element[],
+): void {
+  for (const element of watched) {
+    if (!panels.includes(element)) {
+      sizes.unobserve(element);
+      watched.delete(element);
+    }
+  }
+  for (const element of panels) {
+    if (!watched.has(element)) {
+      sizes.observe(element);
+      watched.add(element);
+    }
+  }
+}

package/src/card/ui/index.ts

@@ -0,0 +1,14 @@
+export type { CardDetailsButtonProps } from './CardDetailsButton.tsx';
+export { CardDetailsButton } from './CardDetailsButton.tsx';
+export type { CardFigureProps } from './CardFigure.tsx';
+export { CardFigure } from './CardFigure.tsx';
+export type { CardFrameProps } from './CardFrame.tsx';
+export { CardFrame } from './CardFrame.tsx';
+export type { CopyTableButtonProps } from './CopyTableButton.tsx';
+export { CopyTableButton } from './CopyTableButton.tsx';
+export {
+  fitCardToFrame,
+  useFitCardToFrame,
+  useOverlayRoom,
+} from './fitCardToFrame.ts';
+export { holdRoomForPanels } from './holdRoomForPanels.ts';

package/src/card/ui/openPanels.ts

@@ -0,0 +1,106 @@
+/**
+ * The dialogs and popovers Blueprint has open over a card, measured as the
+ * room each needs of the card's frame.
+ */
+
+import { Classes } from '@blueprintjs/core';
+
+import type { OpenPanel } from '../core/panelRoom.ts';
+
+/** The panels on screen, and the elements measured for them. */
+export interface FoundPanels {
+  /** What each panel needs. */
+  found: OpenPanel[];
+  /** The elements whose size the panels are read from. */
+  elements: HTMLElement[];
+}
+
+const OPEN = `.${Classes.OVERLAY_OPEN}`;
+
+/** A tooltip is read in passing and closes as the pointer leaves: no room. */
+const POPOVERS = `${OPEN} .${Classes.POPOVER}:not(.${Classes.TOOLTIP})`;
+
+const DIALOGS = `${OPEN} .${Classes.DIALOG}`;
+
+/** A dialog's body, which scrolls past 70 % of the frame's height. */
+const SCROLLED = `.${Classes.DIALOG_BODY_SCROLL_CONTAINER}`;
+
+/**
+ * A control whose popover is open: Blueprint marks its own target, and a
+ * toolbar that renders its target itself — the 3D view's — says it is
+ * expanded.
+ */
+const OPEN_CONTROLS = `.${Classes.POPOVER_OPEN}, [aria-expanded='true']`;
+
+/**
+ * The dialogs and popovers on screen, and the room each needs.
+ * @param card - The card they are opened over.
+ * @returns The panels, and the elements measured for them.
+ */
+export function openPanels(card: HTMLElement): FoundPanels {
+  const found: OpenPanel[] = [];
+  const elements: HTMLElement[] = [];
+  const top = card.getBoundingClientRect().top;
+  for (const dialog of document.querySelectorAll<HTMLElement>(DIALOGS)) {
+    const { marginTop, marginBottom } = globalThis.getComputedStyle(dialog);
+    const margins =
+      (parseLength(marginTop) ?? 0) + (parseLength(marginBottom) ?? 0);
+    found.push({ kind: 'dialog', height: unscrolledHeight(dialog) + margins });
+    elements.push(dialog);
+  }
+  for (const popover of document.querySelectorAll<HTMLElement>(POPOVERS)) {
+    // The box that places a popover is never scaled while it opens, so it
+    // says where the popover ends; the popover itself is, at first.
+    const placed = popover.parentElement?.classList.contains(
+      Classes.POPOVER_TRANSITION_CONTAINER,
+    )
+      ? popover.parentElement
+      : popover;
+    const bottom = placed.getBoundingClientRect().bottom - top;
+    found.push({
+      kind: 'popover',
+      height: unscrolledHeight(popover),
+      ...(bottom > 0 && { bottom }),
+    });
+    elements.push(popover);
+  }
+  return { found, elements };
+}
+
+/**
+ * Where the lowest control of the card whose popover is open ends.
+ * @param card - The card.
+ * @returns Its bottom edge, in pixels from the top of the card; 0 for none.
+ */
+export function anchorBottom(card: HTMLElement): number {
+  const top = card.getBoundingClientRect().top;
+  let bottom = 0;
+  for (const control of card.querySelectorAll(OPEN_CONTROLS)) {
+    const edge = control.getBoundingClientRect().bottom - top;
+    if (edge > bottom) bottom = edge;
+  }
+  return bottom;
+}
+
+/**
+ * The panel's height with what its body scrolls away put back.
+ * @param panel - The dialog or the popover.
+ * @returns Its height, in pixels.
+ */
+function unscrolledHeight(panel: HTMLElement): number {
+  let height = panel.offsetHeight;
+  for (const body of panel.querySelectorAll<HTMLElement>(SCROLLED)) {
+    height += body.scrollHeight - body.clientHeight;
+  }
+  return height;
+}
+
+/**
+ * A computed length, in pixels.
+ * @param value - E.g. `30px`; empty where nothing computes it.
+ * @returns The number, or undefined when it is not one.
+ */
+function parseLength(value: string): number | undefined {
+  const length = Number.parseFloat(value);
+  return Number.isFinite(length) ? length : undefined;
+}

package/src/card.ts

@@ -0,0 +1,13 @@
+/**
+ * The card an answer is shown as in a chat: a site's own page under
+ * `?embed=1&card=1`, framed inline by mcp.cheminfo.org.
+ *
+ * An entry point of its own, and not part of `react-cheminfo/ui`, because it
+ * talks to the frame through `cheminfo-mcp-server/embed`: a site that serves
+ * no tools must never be made to install it. The addresses — `CARD_PARAM`,
+ * `sitePageUrl`, `cardPageUrl` — need neither React nor the frame, and are in
+ * `react-cheminfo/core` too.
+ */
+
+export * from './card/core/index.ts';
+export * from './card/ui/index.ts';

package/src/conformers.ts

@@ -85,3 +85,7 @@ export {
   hasFiniteCoordinates,
 } from './structure/core/conformerShape.ts';
 export { registerResources } from './structure/core/oclResources.ts';
+export {
+  OCL_RESOURCES_FILE,
+  oclResourcesUrl,
+} from './worker/core/oclResourcesUrl.ts';