react-cheminfo 0.28.0 → 0.30.0

package/src/chart/ui/useChartZoom.ts

@@ -0,0 +1,255 @@
+/**
+ * The gestures that move the window a chart is showing.
+ *
+ * A drag zooms the x axis, because that is the axis a chemist reads: the
+ * question is nearly always "what is between 366 and 372", never "what is
+ * between forty and sixty percent". The y axis comes along only when the drag is
+ * released past the baseline, a gesture that cannot be made by accident and one
+ * the preview rectangle announces before the button is let go. The wheel scales
+ * the y axis on its own, bringing up the small features being asked about far
+ * more often than any box around them, and a double click puts the window back.
+ *
+ * Which of them a chart answers is `ZoomGestures`, and a viewer is free to offer
+ * fewer: a drag can be the rectangle it sweeps out, and the wheel can be left to
+ * the page. Neither is a preference to be toggled — it is what the measurement
+ * makes worth doing, and `chartDomain.ts` says why.
+ *
+ * Not every gesture moves the window. A drag can be asked to report the range it
+ * swept out, a press that went nowhere is a click, and a host can refuse a press
+ * outright so that a handle drawn on the chart keeps the gesture aimed at it;
+ * `chartGestures.ts` holds all three, and `zoomDomain.ts` holds what a gesture
+ * does to a window. Neither knows anything of React, which is what lets the
+ * answer to a gesture be read without a chart on screen.
+ *
+ * What the window is fitted *to* is handed in rather than worked out here, and
+ * that is what makes one hook serve every kind of spectrum: fitting reads the
+ * traces, and a mass spectrum's are two per spectrum where an infrared
+ * spectrum's are one in either of two units. `useChartWindow` then holds the
+ * answer each viewer hands over.
+ */
+
+import type { PointerEvent as ReactPointerEvent, RefObject } from 'react';
+import { useCallback, useMemo, useState } from 'react';
+
+import type {
+  ChartDomain,
+  YAxisRules,
+  ZoomGestures,
+  ZoomRules,
+} from '../core/chartDomain.ts';
+import { DEFAULT_ZOOM_GESTURES } from '../core/chartDomain.ts';
+import type { ChartScale } from '../core/chartScale.ts';
+import { chartWheelFactor } from '../core/chartViewport.ts';
+import type { ZoomSelection } from '../core/zoomDomain.ts';
+import { scaledYAxis, zoomSelection } from '../core/zoomDomain.ts';
+
+import type {
+  ChartGestureReports,
+  ChartZoomHandlers,
+  Drag,
+} from './chartGestures.ts';
+import {
+  answeredRelease,
+  draggedTo,
+  releaseDrag,
+  startedDrag,
+} from './chartGestures.ts';
+import type { ChartWindowOptions } from './useChartWindow.ts';
+import { useChartWindow } from './useChartWindow.ts';
+import { useWheelListener } from './useWheelListener.ts';
+
+/** The chart, what it is fitted to, and which gestures it answers. */
+export interface ChartZoomOptions
+  extends ChartWindowOptions, ChartGestureReports {
+  /** The SVG the gestures are made on, as it was handed to its `ref`. */
+  svgRef: RefObject<SVGSVGElement | null>;
+  /**
+   * How the y axis behaves under a gesture — where its baseline is, and whether
+   * that baseline is held in the window.
+   * @default a stick spectrum's: a baseline of zero, always kept
+   */
+  yAxis?: YAxisRules;
+  /**
+   * Which gestures the chart answers: what a drag asks for, and whether the
+   * wheel scales the value axis at all.
+   *
+   * Both together rather than one at a time, because they are one decision. A
+   * viewer that reads its data in more than one way — an infrared spectrum is
+   * read as absorbance or as percent transmittance — settles the whole set from
+   * whatever it is currently reading, and hands it over as it stands.
+   * @default every gesture: a drag along the horizontal axis, and the wheel
+   */
+  gestures?: ZoomGestures;
+}
+
+/** The window, the drag being made in it, and how to work both. */
+export interface ChartZoom {
+  /** What the chart is showing. */
+  domain: ChartDomain;
+  /**
+   * The horizontal axis, as every gesture was measured against it: **draw with
+   * this rather than building one**, since a second scale beside it is a second
+   * chance to get a reversed axis the wrong way round.
+   */
+  xScale: ChartScale;
+  /** The vertical axis, likewise. */
+  yScale: ChartScale;
+  /** The drag being made, `null` when none is. */
+  selection: ZoomSelection | null;
+  /** Put the window back to everything that is drawn. */
+  reset: () => void;
+  /** Put on the SVG. */
+  handlers: ChartZoomHandlers;
+}
+
+/**
+ * Zoom a chart by dragging it, by the wheel and by double clicking it.
+ *
+ * Which window is on screen — the fit, the one a gesture arrived at, or the one
+ * a host imposes — is `useChartWindow`. What is here is what a gesture *is*: the
+ * drag as it is made, the rules it is read under, and the answer it comes to.
+ * @param options - The chart, the fit and how its y axis behaves.
+ * @returns The window and the gestures that move it.
+ */
+export function useChartZoom(options: ChartZoomOptions): ChartZoom {
+  const {
+    fitted,
+    fitKey,
+    yFitKey,
+    svgRef,
+    plot,
+    yAxis,
+    gestures,
+    reverseX = false,
+    domain: imposed = null,
+    onSelectRange,
+    onClick,
+    shouldStartDrag,
+  } = options;
+
+  const { domain, xScale, yScale, show, reset } = useChartWindow({
+    fitted,
+    fitKey,
+    ...(yFitKey === undefined ? {} : { yFitKey }),
+    plot,
+    domain: imposed,
+    reverseX,
+  });
+
+  // Taken apart field by field rather than depending on the object, so a viewer
+  // rebuilding an equal `yAxis` or `gestures` on every render does not rebuild
+  // the rules and every callback hanging off them. Every field has to be listed
+  // here: one left out silently falls back to its default, which is how a
+  // transmittance chart came to answer a mass spectrum's question about its own
+  // baseline.
+  const baseline = yAxis?.baseline;
+  const keepBaseline = yAxis?.keepBaseline;
+  const pointsDown = yAxis?.pointsDown;
+  const dragMode = gestures?.drag ?? DEFAULT_ZOOM_GESTURES.drag;
+  const wheel = gestures?.wheel ?? DEFAULT_ZOOM_GESTURES.wheel;
+  const rules = useMemo<ZoomRules>(
+    () => ({ baseline, keepBaseline, pointsDown, drag: dragMode }),
+    [baseline, keepBaseline, pointsDown, dragMode],
+  );
+
+  const [drag, setDrag] = useState<Drag | null>(null);
+
+  const onWheel = useCallback(
+    (event: WheelEvent) => {
+      // Refused before the event is touched, so a chart that does not answer the
+      // wheel scrolls the page under the pointer exactly as the rest of it does.
+      // Swallowing the gesture and doing nothing with it would be the one
+      // outcome nobody asked for.
+      if (!wheel) return;
+      const factor = chartWheelFactor(event.deltaY, event.deltaMode);
+      if (factor === 1) return;
+      // Heard non-passively for exactly this: without the refusal the chart
+      // zooms and the page scrolls out from under it at the same time.
+      event.preventDefault();
+      show(scaledYAxis(domain, factor, rules.baseline));
+    },
+    [domain, rules.baseline, wheel, show],
+  );
+  useWheelListener(svgRef, onWheel);
+
+  const onPointerDown = useCallback(
+    (event: ReactPointerEvent<SVGSVGElement>) => {
+      const started = startedDrag(event, svgRef.current, shouldStartDrag);
+      if (started !== null) setDrag(started);
+    },
+    [svgRef, shouldStartDrag],
+  );
+
+  const onPointerMove = useCallback(
+    (event: ReactPointerEvent<SVGSVGElement>) => {
+      const moved = draggedTo(drag, event, svgRef.current);
+      if (moved !== null) setDrag(moved);
+    },
+    [drag, svgRef],
+  );
+
+  const onPointerUp = useCallback(
+    (event: ReactPointerEvent<SVGSVGElement>) => {
+      if (drag?.pointerId !== event.pointerId) return;
+      releaseDrag(event);
+      setDrag(null);
+      const released = draggedTo(drag, event, svgRef.current) ?? drag;
+      const next = answeredRelease(
+        domain,
+        released,
+        plot,
+        xScale,
+        yScale,
+        rules,
+        { onSelectRange, onClick },
+        // Read off the release rather than off the press, because that is where
+        // the reader was looking and what `reportClick` already inverts.
+        { shift: event.shiftKey, alt: event.altKey },
+      );
+      if (next !== null) show(next);
+    },
+    [
+      drag,
+      domain,
+      plot,
+      xScale,
+      yScale,
+      svgRef,
+      rules,
+      onSelectRange,
+      onClick,
+      show,
+    ],
+  );
+
+  const onPointerCancel = useCallback(
+    (event: ReactPointerEvent<SVGSVGElement>) => {
+      if (drag?.pointerId !== event.pointerId) return;
+      releaseDrag(event);
+      setDrag(null);
+    },
+    [drag],
+  );
+
+  const selection = useMemo(
+    () => zoomSelection(drag, yScale, rules),
+    [drag, yScale, rules],
+  );
+
+  return {
+    domain,
+    xScale,
+    yScale,
+    selection,
+    reset,
+    handlers: {
+      onPointerDown,
+      onPointerMove,
+      onPointerUp,
+      onPointerCancel,
+      onDoubleClick: reset,
+    },
+  };
+}
+
+export { type ChartZoomHandlers } from './chartGestures.ts';

package/src/chart/ui/useWheelListener.ts

@@ -0,0 +1,62 @@
+/**
+ * The wheel over an element, heard loudly enough to refuse the page its
+ * scroll.
+ *
+ * React's `onWheel` is registered passively — the browser is told in advance
+ * that the page may scroll before the handler has had its say — so calling
+ * `preventDefault` inside it does nothing at all: the chart zooms and the page
+ * scrolls out from under it at the same time. The only way to be heard is to
+ * register the listener on the element directly with `{ passive: false }`,
+ * which is what this hook exists to do; nothing else about the gesture belongs
+ * here.
+ *
+ * The listener is attached once and reads the handler through a ref refreshed
+ * on every commit. Both halves are needed: attaching once is what keeps a
+ * pointer resting over the chart from re-registering a listener sixty times a
+ * second, and reading the handler live is what stops that one listener from
+ * zooming the window as it stood when the chart was mounted.
+ */
+
+import type { RefObject } from 'react';
+import { useEffect, useLayoutEffect, useRef } from 'react';
+
+/**
+ * Hear the wheel over an element.
+ * @param ref - The element, as it was handed to its `ref`.
+ * @param handler - What to do with the wheel; free to be an inline arrow, since
+ * it is read at the moment the wheel turns rather than closed over when the
+ * listener is attached. It is the handler's own business to call
+ * `preventDefault` — the listener is registered so that the call is honoured,
+ * not so that it is made.
+ */
+export function useWheelListener<T extends Element>(
+  ref: RefObject<T | null>,
+  handler: (event: WheelEvent) => void,
+): void {
+  const latest = useRef(handler);
+  useLayoutEffect(() => {
+    latest.current = handler;
+  });
+
+  useEffect(() => {
+    const element = ref.current;
+    if (element === null) return;
+    // Typed as the plain `Event` the element's own listener map hands it: an
+    // `Element` is not known to carry a wheel, so the narrowing is done here.
+    function onWheel(event: Event) {
+      if (event instanceof WheelEvent) latest.current(event);
+    }
+    element.addEventListener('wheel', onWheel, WHEEL_LISTENER);
+    return () => {
+      element.removeEventListener('wheel', onWheel);
+    };
+  }, [ref]);
+}
+
+/**
+ * Registered non-passively, which is the whole reason this hook exists. Nothing
+ * is passed back on removal: a listener is matched on its type, its function
+ * and its capture flag alone, and passing the options object there is a type
+ * error rather than a courtesy.
+ */
+const WHEEL_LISTENER = { passive: false } as const;

package/src/chrome/ui/AccountButton.tsx

@@ -0,0 +1,185 @@
+import { Menu, MenuDivider, MenuItem, PopoverNext } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+
+import { NavLink } from './NavLink.tsx';
+import type { NavItem } from './navItem.ts';
+import { isModifiedClick } from './navItem.ts';
+
+/** Who the site is answering to. */
+export interface AccountIdentity {
+  /** What the person is called on screen. */
+  name: string;
+  /**
+   * What tells the account apart under that name — the address it is held at,
+   * the handle it was opened with.
+   * @default undefined
+   */
+  detail?: string;
+  /**
+   * The letters the mark is drawn with.
+   * @default the first letter of each of the first two words of `name`
+   */
+  initials?: string;
+}
+
+export interface AccountButtonProps {
+  /** Who is signed in, or `null` when nobody is. */
+  identity: AccountIdentity | null;
+  /**
+   * Whether the site has not heard back yet. Neither state is drawn until it
+   * has: a bar that offers to sign in and then turns into a name has told the
+   * visitor something false, and it is the state they act on first.
+   * @default false
+   */
+  loading?: boolean;
+  /**
+   * The address signing in happens at, for a site with a page of its own for
+   * it. Writing it keeps the entry a real link, so a middle click opens a tab.
+   * @default undefined
+   */
+  signInHref?: string;
+  /**
+   * What the site does when the invitation is picked — route to that page, or
+   * open a credentials dialog for a site that has no page.
+   * @default undefined
+   */
+  onSignIn?: () => void;
+  /**
+   * What the site does when Sign out is picked.
+   * @default undefined
+   */
+  onSignOut?: () => void;
+  /**
+   * What the invitation reads, for a site whose accounts are for one kind of
+   * person — "Teacher sign in". Two words: it is written out in the bar rather
+   * than folded into a glyph.
+   * @default the chrome's own word for it, in the language of the page
+   */
+  signInLabel?: string;
+  /**
+   * The account's own pages, listed above Sign out — a profile, a settings
+   * page.
+   * @default undefined
+   */
+  items?: readonly NavItem[];
+}
+
+/**
+ * The one utility of the bar that says who the site is answering to: an
+ * invitation when nobody is signed in, and the account's mark when somebody is.
+ *
+ * The two states are told apart by whether an identity is on screen, never by
+ * the direction of an arrow. Blueprint's `log-in` and `log-out` are the same
+ * arrow either side of the same door, and at 14 px among four other monochrome
+ * glyphs nobody reads which side it is on — a site drawing one reports the
+ * visitor as signed in while they are signed out. So the invitation is the
+ * words `Sign in`, which no mark can be mistaken for, and being signed in is
+ * the person's own initials.
+ * @param props - Who is signed in, what signing in and out do, and the pages
+ * the account's menu lists.
+ * @returns The entry, or nothing while the site is still asking.
+ */
+export function AccountButton(props: AccountButtonProps): ReactElement | null {
+  const {
+    identity,
+    loading = false,
+    signInHref,
+    onSignIn,
+    onSignOut,
+    signInLabel,
+    items = [],
+  } = props;
+  const t = useChromeT();
+
+  if (loading) {
+    // The width of the mark, so the bar does not jump when the answer lands.
+    return <span className="account-button__pending" aria-hidden="true" />;
+  }
+
+  if (identity === null) {
+    return (
+      <NavLink
+        className="account-button account-button--out"
+        item={{
+          id: 'account',
+          label: signInLabel ?? t('account.signIn'),
+          href: signInHref,
+          onSelect: onSignIn,
+        }}
+      />
+    );
+  }
+
+  const { name, detail, initials = initialsOf(name) } = identity;
+
+  return (
+    <PopoverNext
+      placement="bottom-end"
+      content={
+        <Menu className="nav-menu account-menu">
+          <li className="account-menu__identity">
+            <span className="account-menu__name">{name}</span>
+            {detail === undefined ? null : (
+              <span className="account-menu__detail">{detail}</span>
+            )}
+          </li>
+          <MenuDivider />
+          {items.map((item) => (
+            <MenuItem
+              key={item.id}
+              icon={item.icon}
+              text={item.label}
+              href={item.href}
+              target={item.external ? '_blank' : undefined}
+              onClick={(event) => {
+                if (item.onSelect === undefined || isModifiedClick(event)) {
+                  return;
+                }
+                event.preventDefault();
+                item.onSelect();
+              }}
+            />
+          ))}
+          {items.length === 0 ? null : <MenuDivider />}
+          <MenuItem
+            icon="log-out"
+            text={t('account.signOut')}
+            onClick={onSignOut}
+          />
+        </Menu>
+      }
+    >
+      <button
+        type="button"
+        className="nav-link nav-link--icon account-button account-button--in"
+        title={t('account.signedInAs', { name })}
+        aria-label={t('account.signedInAs', { name })}
+      >
+        <span className="account-mark">{initials}</span>
+      </button>
+    </PopoverNext>
+  );
+}
+
+/**
+ * The letters a name is marked with: the first of each of its first two words,
+ * or the first two letters of a name written as one word.
+ * @param name - What the person is called.
+ * @returns One or two letters, in capitals.
+ */
+function initialsOf(name: string): string {
+  const [first, second] = name.split(/\s+/).filter((word) => word !== '');
+  if (first === undefined) return '?';
+  if (second === undefined) return firstWordInitials(first);
+  return `${first.charAt(0)}${second.charAt(0)}`.toUpperCase();
+}
+
+// A single word is usually a handle or an address, where the two letters say
+// more than one does — but never the part after the `@`, which every account
+// on the same domain would share.
+function firstWordInitials(word: string): string {
+  const [local = ''] = word.split('@');
+  return (local === '' ? word : local).slice(0, 2).toUpperCase();
+}

package/src/chrome/ui/index.ts

@@ -1,3 +1,5 @@
+export type { AccountButtonProps, AccountIdentity } from './AccountButton.tsx';
+export { AccountButton } from './AccountButton.tsx';
 export type { HeaderToggleOption, HeaderToggleProps } from './HeaderToggle.tsx';
 export { HeaderToggle } from './HeaderToggle.tsx';
 export type { NavItem } from './navItem.ts';

package/src/clipboard/core/copyPng.ts

@@ -0,0 +1,20 @@
+/**
+ * Put a PNG on the clipboard.
+ *
+ * The image is handed over as a promise rather than as a blob on purpose:
+ * Safari only allows a clipboard write that the click itself started, so the
+ * item has to be built while the handler is still running and the
+ * rasterization awaited by the clipboard rather than before it.
+ * @param png - The image being rasterized.
+ * @returns Whether it was copied. `false` outside a secure context, and in a
+ *   browser whose clipboard takes text only.
+ */
+export async function writeImageToClipboard(
+  png: Promise<Blob>,
+): Promise<boolean> {
+  if (typeof ClipboardItem === 'undefined' || !navigator.clipboard?.write) {
+    return false;
+  }
+  await navigator.clipboard.write([new ClipboardItem({ 'image/png': png })]);
+  return true;
+}

package/src/clipboard/core/index.ts

@@ -1,3 +1,4 @@
+export { writeImageToClipboard } from './copyPng.ts';
 export type { WriteBlobToClipboardOptions } from './writeBlobToClipboard.ts';
 export { writeBlobToClipboard } from './writeBlobToClipboard.ts';
 export type { ClipboardContent, ClipboardText } from './writeToClipboard.ts';

package/src/clipboard/ui/ClickToCopy.tsx

@@ -71,6 +71,12 @@ export interface ClickToCopyProps {
    * @default undefined
    */
   style?: CSSProperties;
+  /**
+   * `data-testid` the element carries, so an end-to-end suite can select the
+   * value without depending on the text inside it.
+   * @default undefined
+   */
+  testId?: string;
 }
 
 /** Past this length the value is left out of the title: a molfile is no tooltip. */
@@ -106,13 +112,14 @@ export function ClickToCopy(props: ClickToCopyProps): ReactElement {
     disabled = false,
     className,
     style,
+    testId,
   } = props;
   const t = useChromeT();
   const { copied, failed, copy } = useCopyToClipboard();
 
   if (disabled) {
     return (
-      <Element className={className} style={style}>
+      <Element className={className} style={style} data-testid={testId}>
         {children}
       </Element>
     );
@@ -138,6 +145,7 @@ export function ClickToCopy(props: ClickToCopyProps): ReactElement {
         className,
       )}
       style={style}
+      data-testid={testId}
       role={focusable && !CELLS.has(Element) ? 'button' : undefined}
       tabIndex={focusable ? 0 : undefined}
       title={title ?? copyTitle(value, label, t)}

package/src/core.ts

@@ -14,6 +14,7 @@ export * from './i18n/core/index.ts';
 export * from './language/core/index.ts';
 export * from './orbital/core/index.ts';
 export * from './overlay/core/index.ts';
+export * from './panel/core/index.ts';
 export * from './parallel/core/index.ts';
 export * from './pedagogy/core/index.ts';
 export * from './periodic/core/index.ts';

package/src/download/core/exportStyles.ts

@@ -0,0 +1,20 @@
+/**
+ * A row of buttons with the name box among them, wrapping when the dialog is
+ * too narrow for them.
+ */
+export const exportButtonsStyle = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: 6,
+} as const;
+
+/** One group of an export dialog: what it offers, in a column. */
+export const exportSectionStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 8,
+} as const;
+
+/** Text that says something about a control rather than being one. */
+export const exportNoteStyle = { fontSize: 12, opacity: 0.7 } as const;