react-cheminfo 0.50.0 → 0.51.0

package/src/molecule3d/ui/useImageExport.ts

@@ -1,11 +1,16 @@
 import type { RefObject } from 'react';
 import { useCallback } from 'react';
 
+import type { FigureNotice } from '../../download/core/copyFigure.ts';
+import { copyFigure } from '../../download/core/copyFigure.ts';
 import type { FigureFormat } from '../../download/core/downloadFigure.ts';
 import type { FigurePixels } from '../../download/core/figureScale.ts';
 
 import type { SceneCapture } from './exportMoleculeImage.ts';
-import { exportMoleculeImage } from './exportMoleculeImage.ts';
+import {
+  captureMoleculePng,
+  exportMoleculeImage,
+} from './exportMoleculeImage.ts';
 
 /** What {@link useImageExport} hands the export panel. */
 export interface ImageExport {
@@ -13,10 +18,15 @@ export interface ImageExport {
   canvasSize: () => FigurePixels | null;
   /** Render the scene at `scale` and download it as `format`. */
   exportImage: (format: FigureFormat, scale: number) => Promise<void>;
+  /**
+   * Render the scene at `scale` and put it on the clipboard as a PNG. Call it
+   * from the click itself: Safari only allows a write the click started.
+   */
+  copyImage: (scale: number) => Promise<FigureNotice>;
 }
 
 /**
- * The two callbacks the export panel needs, bound to the canvas and its viewer.
+ * The callbacks the export panel needs, bound to the canvas and its viewer.
  * @param container - The element molstar draws into.
  * @param viewerRef - The viewer, once created.
  * @param fileName - File name without its extension.
@@ -46,5 +56,17 @@ export function useImageExport(
     [canvasSize, viewerRef, fileName],
   );
 
-  return { canvasSize, exportImage };
+  const copyImage = useCallback(
+    (scale: number) => {
+      const viewer = viewerRef.current;
+      const size = canvasSize();
+      if (viewer === null || size === null) {
+        return Promise.reject(new Error('There is no picture to copy yet.'));
+      }
+      return copyFigure(captureMoleculePng(viewer, scale, size));
+    },
+    [canvasSize, viewerRef],
+  );
+
+  return { canvasSize, exportImage, copyImage };
 }

package/src/overlay/ui/FigureBar.tsx

@@ -0,0 +1,96 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useMemo, useRef } from 'react';
+
+import { useContainerSize } from '../../hooks/ui/useContainerSize.ts';
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
+import type { OverlayDensity } from '../core/overlayMetrics.ts';
+import { overlayMetrics } from '../core/overlayMetrics.ts';
+
+import type { OverlayBarProps } from './OverlayBar.tsx';
+import { OverlayBar } from './OverlayBar.tsx';
+import type { OverlaySurface } from './overlaySurface.ts';
+import {
+  OverlaySurfaceContext,
+  useCoarsePointer,
+  useOverlaySurface,
+} from './overlaySurface.ts';
+import { useFigureBarAwake } from './useFigureBarAwake.ts';
+
+/** What {@link FigureBar} needs. */
+export interface FigureBarProps extends Omit<
+  OverlayBarProps,
+  'placement' | 'restingOpacity' | 'children'
+> {
+  /**
+   * The controls at the start of the row — how the figure is drawn, such as
+   * its axis scales. They never fold.
+   * @default undefined — the start of the row is empty
+   */
+  children?: ReactNode;
+  /**
+   * How tightly the bar packs its controls. A coarse pointer wins over this,
+   * whatever it says.
+   * @default 'compact'
+   */
+  density?: OverlayDensity;
+  /**
+   * Class the bar carries, in addition to `figure-bar no-print`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The controls of a figure, in one bar spanning the width above it.
+ *
+ * Settings read from the left edge — `children`, which never fold, then `end`,
+ * which folds behind a cog on a narrow figure — and the glyphs keep the right
+ * one: the `?` in `info`, saving and printing in `tools`. Every figure of the
+ * family is laid out this way, so the reader finds both in the same place.
+ *
+ * Put it right before the figure, never inside its box, and give the two a
+ * parent of their own: it is in the flow, so it covers neither the data nor
+ * the axes, and with `rest` it wakes while that parent is pointed at. It measures its own width to decide
+ * what folds, is left out of a printed page, and is marked as chrome so that
+ * saving a figure it sits inside saves the picture without it.
+ * @param props - See {@link FigureBarProps}.
+ * @returns The bar.
+ */
+export function FigureBar(props: FigureBarProps): ReactElement {
+  const { children, density = 'compact', className, ...bar } = props;
+  const { rest = 'visible' } = props;
+  const box = useRef<HTMLDivElement>(null);
+  const { width } = useContainerSize(box);
+  const above = useOverlaySurface();
+  const pointer = useCoarsePointer() ? 'coarse' : 'fine';
+  // A finger has nothing to point with until it touches, so it never rests.
+  const awake = useFigureBarAwake(
+    box,
+    rest !== 'visible' && pointer === 'fine',
+  );
+
+  const surface = useMemo<OverlaySurface>(
+    () => ({
+      ...above,
+      metrics: overlayMetrics(density, pointer),
+      awake,
+      pointer,
+      width,
+    }),
+    [above, density, awake, pointer, width],
+  );
+
+  return (
+    <div
+      ref={box}
+      className={joinClassNames('figure-bar no-print', className)}
+      data-figure="chrome"
+    >
+      <OverlaySurfaceContext.Provider value={surface}>
+        <OverlayBar {...bar} placement="stretch">
+          {children}
+        </OverlayBar>
+      </OverlaySurfaceContext.Provider>
+    </div>
+  );
+}

package/src/overlay/ui/OverlayBar.tsx

@@ -9,6 +9,7 @@ import type { OverlayPlacement } from '../core/overlayPlacement.ts';
 import { OverlayBarCard } from './OverlayBarCard.tsx';
 import { OverlayBarStrip } from './OverlayBarStrip.tsx';
 import type { OverlayPanel } from './OverlayPanel.tsx';
+import type { OverlayBarRest } from './overlayBarShape.ts';
 import { OVERLAY_RESTING_OPACITY } from './overlayStyles.ts';
 import { useOverlaySurface } from './overlaySurface.ts';
 
@@ -21,10 +22,11 @@ export interface OverlayBarProps {
    */
   children: ReactNode;
   /**
-   * What sits at the far end of the row: the controls belonging to whatever
-   * the figure is currently showing. They are the first thing to go when the
-   * figure is too narrow for both ends, folding in behind the button.
-   * @default undefined — the bar's end holds only its glyphs
+   * The controls belonging to whatever the figure is currently showing. On a
+   * card they close the row; on a stretched bar they follow the start, left
+   * aligned, and only the glyphs keep the right edge. They are the first
+   * thing to go when the figure is too narrow, folding in behind the button.
+   * @default undefined — the bar holds only its start and its glyphs
    */
   end?: ReactNode;
   /**
@@ -73,6 +75,13 @@ export interface OverlayBarProps {
    * @default 0.74
    */
   restingOpacity?: number;
+  /**
+   * How a stretched bar's controls are drawn while nothing points at the
+   * figure: at full strength, faded, or not at all. The bar keeps its height
+   * whichever it is. A card ignores it: its rest is `restingOpacity`.
+   * @default 'visible'
+   */
+  rest?: OverlayBarRest;
   /**
    * Whether the bar is reduced to a button opening the same controls in a
    * popover. Left out, it folds on its own once the figure is narrower than
@@ -135,7 +144,7 @@ export function OverlayBar(props: OverlayBarProps): ReactElement {
   const name = label ?? t('overlay.options');
   const { collapsed, defaultCollapsed = false } = props;
   const { collapseBelow = 420, moreIcon = 'cog', testId } = props;
-  const { morePadded = true } = props;
+  const { morePadded = true, rest } = props;
   const { width } = useOverlaySurface();
   const [startedFolded] = useState(defaultCollapsed);
 
@@ -158,6 +167,7 @@ export function OverlayBar(props: OverlayBarProps): ReactElement {
         moreIcon={moreIcon}
         morePadded={morePadded}
         folded={folded}
+        rest={rest}
         testId={testId}
       >
         {children}

package/src/overlay/ui/OverlayBarStrip.tsx

@@ -3,15 +3,18 @@ import type { ReactElement } from 'react';
 import { OverlayBarButton } from './OverlayBarButton.tsx';
 import type { OverlayBarShapeProps } from './overlayBarShape.ts';
 import {
-  OVERLAY_BAR_GROUND_STYLE,
   overlayBarContentStyle,
+  overlayBarGroundStyle,
+  overlayBarGroupStyle,
+  overlayBarRestStyle,
   overlayBarSideStyle,
   overlayCardStyle,
 } from './overlayStyles.ts';
 import { useOverlaySurface } from './overlaySurface.ts';
 
 /**
- * The bar that spans the width of the figure, its two ends pushed apart.
+ * The bar that spans the width of the figure: the settings from the left edge,
+ * the glyphs — help, saving, the button the rest folds into — at the right.
  *
  * It is in the flow above the picture rather than on it, and its ground is
  * solid rather than translucent, because a strip reaching from one edge of the
@@ -26,35 +29,44 @@ import { useOverlaySurface } from './overlaySurface.ts';
  */
 export function OverlayBarStrip(props: OverlayBarShapeProps): ReactElement {
   const { children, end, tools, info, more, placement, label } = props;
-  const { moreIcon, morePadded, folded, testId } = props;
-  const { metrics } = useOverlaySurface();
+  const { moreIcon, morePadded, folded, testId, rest = 'visible' } = props;
+  const { metrics, awake } = useOverlaySurface();
 
   const opens = more !== undefined || (folded && end !== undefined);
 
   return (
     <div style={overlayCardStyle(placement, metrics)} data-testid={testId}>
-      <div style={OVERLAY_BAR_GROUND_STYLE} />
-      <div style={overlayBarContentStyle(metrics)}>
-        <div style={overlayBarSideStyle(metrics)}>{children}</div>
+      <div style={overlayBarGroundStyle(rest, awake)} />
+      <div
+        style={{
+          ...overlayBarContentStyle(metrics),
+          ...overlayBarRestStyle(rest, awake),
+        }}
+      >
+        {children === null || children === undefined ? null : (
+          <div style={overlayBarSideStyle(metrics)}>{children}</div>
+        )}
         <div
           role="group"
           aria-label={label}
-          style={overlayBarSideStyle(metrics)}
+          style={overlayBarGroupStyle(metrics)}
         >
-          {folded ? null : end}
-          {tools}
-          {info}
-          {opens ? (
-            <OverlayBarButton
-              placement={placement}
-              label={label}
-              icon={moreIcon}
-              padded={morePadded}
-            >
-              {folded ? end : null}
-              {more}
-            </OverlayBarButton>
-          ) : null}
+          <div style={overlayBarSideStyle(metrics)}>{folded ? null : end}</div>
+          <div style={overlayBarSideStyle(metrics)}>
+            {tools}
+            {info}
+            {opens ? (
+              <OverlayBarButton
+                placement={placement}
+                label={label}
+                icon={moreIcon}
+                padded={morePadded}
+              >
+                {folded ? end : null}
+                {more}
+              </OverlayBarButton>
+            ) : null}
+          </div>
         </div>
       </div>
     </div>

package/src/overlay/ui/OverlayIconButton.tsx

@@ -7,7 +7,7 @@ import { useOverlaySurface } from './overlaySurface.ts';
 import { useOverlayInteraction } from './useOverlayInteraction.ts';
 
 /** What {@link OverlayIconButton} needs. */
-interface OverlayIconButtonProps {
+export interface OverlayIconButtonProps {
   /**
    * The glyph: a Blueprint icon name, or an element of the caller's own — an
    * inline `<svg>` drawing the very mark the figure draws, which is the one
@@ -59,6 +59,13 @@ interface OverlayIconButtonProps {
    * @default undefined — nothing of its own happens
    */
   onClick?: () => void;
+  /**
+   * Whether the pointer is left without the browser's own tooltip, for a
+   * button that already opens a card of its own on hover: the two would
+   * otherwise stack. The screen reader is still told the name.
+   * @default false
+   */
+  untitled?: boolean;
   /**
    * Value of the `data-testid` attribute.
    * @default undefined
@@ -81,6 +88,7 @@ interface OverlayIconButtonProps {
 export function OverlayIconButton(props: OverlayIconButtonProps): ReactElement {
   const { icon, label, value, active = false, disabled = false } = props;
   const { disabledReason, opensMenu = false, onClick, testId } = props;
+  const { untitled = false } = props;
   const { metrics } = useOverlaySurface();
   const { hovered, focused, handlers } = useOverlayInteraction();
 
@@ -91,7 +99,7 @@ export function OverlayIconButton(props: OverlayIconButtonProps): ReactElement {
     <button
       type="button"
       className="no-print"
-      title={told}
+      title={untitled ? undefined : told}
       aria-label={name}
       aria-haspopup={opensMenu ? 'menu' : undefined}
       aria-expanded={opensMenu ? active : undefined}

package/src/overlay/ui/index.ts

@@ -9,6 +9,8 @@
  * belong to the same tool.
  */
 
+export type { FigureBarProps } from './FigureBar.tsx';
+export { FigureBar } from './FigureBar.tsx';
 export type { OverlayActionProps } from './OverlayAction.tsx';
 export { OverlayAction } from './OverlayAction.tsx';
 export type { OverlayBarProps } from './OverlayBar.tsx';
@@ -20,6 +22,8 @@ export { OverlayChip } from './OverlayChip.tsx';
 export { OverlayDivider } from './OverlayDivider.tsx';
 export type { OverlayGroupProps } from './OverlayGroup.tsx';
 export { OverlayGroup } from './OverlayGroup.tsx';
+export type { OverlayIconButtonProps } from './OverlayIconButton.tsx';
+export { OverlayIconButton } from './OverlayIconButton.tsx';
 export type { OverlayInfoProps } from './OverlayInfo.tsx';
 export { OverlayInfo } from './OverlayInfo.tsx';
 export type { OverlayLayerProps } from './OverlayLayer.tsx';

package/src/overlay/ui/overlayBarShape.ts

@@ -12,6 +12,19 @@ import type { ReactNode } from 'react';
 
 import type { OverlayPlacement } from '../core/overlayPlacement.ts';
 
+/**
+ * How a stretched bar's controls are drawn while nothing points at the figure
+ * it belongs to. The bar keeps its height in every case, so nothing under it
+ * moves when it wakes.
+ *
+ * - `visible` — at full strength, always.
+ * - `quiet` — faded, so the bar still says how the figure is drawn without
+ *   drawing the eye; full strength on pointing or focus.
+ * - `hidden` — an empty strip until the figure is pointed at or a control
+ *   holds the focus.
+ */
+export type OverlayBarRest = 'visible' | 'quiet' | 'hidden';
+
 /** What both shapes of a bar are drawn from, with every default resolved. */
 export interface OverlayBarShapeProps {
   /** The controls at the start of the row. */
@@ -46,6 +59,12 @@ export interface OverlayBarShapeProps {
   morePadded: boolean;
   /** Whether the bar has folded its controls away behind that button. */
   folded: boolean;
+  /**
+   * How a stretched bar's controls are drawn while nothing points at the
+   * figure.
+   * @default 'visible'
+   */
+  rest?: OverlayBarRest;
   /**
    * Value of the `data-testid` attribute of the bar.
    * @default undefined

package/src/overlay/ui/overlayStyles.ts

@@ -204,6 +204,67 @@ export function overlayBarContentStyle(metrics: OverlayMetrics): CSSProperties {
   };
 }
 
+/** How strong a quiet bar's controls are drawn while it rests. */
+export const OVERLAY_QUIET_OPACITY = 0.45;
+
+/**
+ * How much of a resting bar's ground is left: almost none, so the strip reads
+ * as the page behind it until the figure is pointed at.
+ */
+export const OVERLAY_RESTING_GROUND_OPACITY = 0.08;
+
+/**
+ * The opacity of a stretched bar's controls.
+ * @param rest - How the bar rests.
+ * @param awake - Whether the figure is pointed at or a control holds the focus.
+ * @returns The rules fading the controls, never the ground under them.
+ */
+export function overlayBarRestStyle(
+  rest: 'visible' | 'quiet' | 'hidden',
+  awake: boolean,
+): CSSProperties {
+  if (rest === 'visible') return {};
+  const opacity = awake ? 1 : rest === 'quiet' ? OVERLAY_QUIET_OPACITY : 0;
+  return { opacity, transition: 'opacity 150ms ease-out' };
+}
+
+/**
+ * The ground of a stretched bar — its surface and the hairline under it —
+ * faded with its controls, so a resting bar is the page's own grey.
+ * @param rest - How the bar rests.
+ * @param awake - Whether the figure is pointed at or a control holds the focus.
+ * @returns The ground's rules.
+ */
+export function overlayBarGroundStyle(
+  rest: 'visible' | 'quiet' | 'hidden',
+  awake: boolean,
+): CSSProperties {
+  if (rest === 'visible') return OVERLAY_BAR_GROUND_STYLE;
+  return {
+    ...OVERLAY_BAR_GROUND_STYLE,
+    opacity: awake ? 1 : OVERLAY_RESTING_GROUND_OPACITY,
+    transition: 'opacity 150ms ease-out',
+  };
+}
+
+/**
+ * Everything on a stretched bar after its start: the settings, then the glyphs
+ * pushed to the right edge, so settings always read from the left and the `?`
+ * and the save glyph are always found in the same corner.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The group's rules.
+ */
+export function overlayBarGroupStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    display: 'flex',
+    flex: '1 1 auto',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    gap: metrics.gap,
+    minWidth: 0,
+  };
+}
+
 /**
  * One end of a stretched bar.
  *

package/src/overlay/ui/useFigureBarAwake.ts

@@ -0,0 +1,56 @@
+import type { RefObject } from 'react';
+import { useEffect, useState } from 'react';
+
+/** How long the bar stays awake after the pointer leaves, so a reader moving to a menu does not watch it fade. */
+const SLEEP_DELAY = 300;
+
+/**
+ * Whether a figure's bar is awake: the box holding the bar and its figure is
+ * pointed at, or the focus is in the bar or in a popover one of its controls
+ * opened.
+ * @param bar - The bar; its parent is the box holding the figure it configures.
+ * @param watching - Whether to watch at all. A bar that never rests is always
+ * awake and listens to nothing.
+ * @returns Whether the bar is awake.
+ */
+export function useFigureBarAwake(
+  bar: RefObject<HTMLElement | null>,
+  watching: boolean,
+): boolean {
+  const [pointed, setPointed] = useState(false);
+  const [focused, setFocused] = useState(false);
+
+  useEffect(() => {
+    const figure = bar.current?.parentElement;
+    if (!watching || figure === null || figure === undefined) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const enter = () => {
+      clearTimeout(timer);
+      setPointed(true);
+    };
+    const leave = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => setPointed(false), SLEEP_DELAY);
+    };
+    // A menu opened from the bar is portalled out of it; the focus inside it
+    // still belongs to the bar, so the trigger does not vanish under it.
+    const focusIn = (event: FocusEvent) => {
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+      const inBar = bar.current?.contains(target) ?? false;
+      const inPortal = target.closest('.bp6-portal') !== null;
+      setFocused((was) => inBar || (was && inPortal));
+    };
+    figure.addEventListener('pointerenter', enter);
+    figure.addEventListener('pointerleave', leave);
+    document.addEventListener('focusin', focusIn);
+    return () => {
+      clearTimeout(timer);
+      figure.removeEventListener('pointerenter', enter);
+      figure.removeEventListener('pointerleave', leave);
+      document.removeEventListener('focusin', focusIn);
+    };
+  }, [bar, watching]);
+
+  return !watching || pointed || focused;
+}

package/src/periodic/core/elements.ts

@@ -9,9 +9,12 @@
  * they still agree with it.
  *
  * `block` follows the element's *position* in the table, which is what a
- * student reads off it. The configuration is the authority on which subshell is
- * actually filling, and the two disagree for a handful of elements — lanthanum
- * fills 5d, not 4f. See `ELEMENT_ANOMALIES` in the orbital module.
+ * student reads off it, with two exceptions where the table's shape and the
+ * chemistry part ways: helium is s, and lutetium and lawrencium close the d
+ * block in group 3 (IUPAC), so the f block is fourteen wide. The configuration
+ * is the authority on which subshell is actually filling, and the two disagree
+ * for a handful of elements — lanthanum fills 5d, not 4f. See
+ * `ELEMENT_ANOMALIES` in the orbital module.
  */
 
 /** Region of the table an element sits in. */
@@ -210,6 +213,8 @@ export function elementByAtomicNumber(
 }
 
 function blockOf(atomicNumber: number, group: number | null): ElementBlock {
+  // Lutetium and lawrencium are drawn in the f rows but belong to group 3.
+  if (atomicNumber === 71 || atomicNumber === 103) return 'd';
   if (group === null) return 'f';
   // Helium sits above the p block but its only electrons are 1s.
   if (atomicNumber === 2) return 's';

package/src/periodic/core/index.ts

@@ -15,8 +15,15 @@ export {
   UNKNOWN_SWATCH,
   categorySwatch,
 } from './categories.ts';
-export type { Cell, ElementPick, ElementRange } from './layout.ts';
+export type {
+  BlockRange,
+  Cell,
+  ElementPick,
+  ElementRange,
+  NumberedRange,
+} from './layout.ts';
 export {
+  BLOCK_LABELS,
   COLUMN_COUNT,
   EMPTY_BLOCK,
   INNER_TRANSITION_MARKERS,

package/src/periodic/core/layout.ts

@@ -11,11 +11,23 @@
  * by one; nothing in this module needs to know that.
  */
 
-import type { ElementCategory, PeriodicElement } from './elements.ts';
+import type {
+  ElementBlock,
+  ElementCategory,
+  PeriodicElement,
+} from './elements.ts';
 import { PERIODIC_ELEMENTS, elementBySymbol } from './elements.ts';
 
-/** A whole run of the table: one group, or one period. */
-export interface ElementRange {
+/**
+ * A whole run of the table: one group, one period, or one block.
+ *
+ * Narrow on `kind` before reading `value`: a group or a period is numbered, a
+ * block is lettered.
+ */
+export type ElementRange = NumberedRange | BlockRange;
+
+/** One group or one period. */
+export interface NumberedRange {
   /** Whether the run is a group or a period. */
   kind: 'group' | 'period';
   /** Its number: a group from 1 to 18, a period from 1 to 7. */
@@ -28,6 +40,16 @@ export interface ElementRange {
   additive: boolean;
 }
 
+/** One block: the elements whose last electron enters the same subshell. */
+export interface BlockRange {
+  /** A block. */
+  kind: 'block';
+  /** Its letter. */
+  value: ElementBlock;
+  /** As for {@link NumberedRange.additive}. */
+  additive: boolean;
+}
+
 /** One element, and what the click that picked it asked for. */
 export interface ElementPick {
   /**
@@ -137,6 +159,26 @@ export const INNER_TRANSITION_MARKERS: ReadonlyArray<{
   { cell: { column: 3, row: 7 }, label: '89–103', category: 'actinoid' },
 ];
 
+/**
+ * Where each block is named, in the cells no element occupies: s, d and p
+ * along the spacer under period 7, each under the columns it holds, and f in
+ * the two cells left of the inner-transition rows.
+ *
+ * Helium is an s element standing over the p block; a label follows the
+ * columns, and the element its electrons.
+ */
+export const BLOCK_LABELS: ReadonlyArray<{
+  block: ElementBlock;
+  cell: Cell;
+  columnSpan: number;
+  rowSpan: number;
+}> = [
+  { block: 's', cell: { column: 1, row: 8 }, columnSpan: 2, rowSpan: 1 },
+  { block: 'd', cell: { column: 3, row: 8 }, columnSpan: 10, rowSpan: 1 },
+  { block: 'p', cell: { column: 13, row: 8 }, columnSpan: 6, rowSpan: 1 },
+  { block: 'f', cell: { column: 1, row: 9 }, columnSpan: 2, rowSpan: 2 },
+];
+
 /** The period each inner-transition row belongs to, for its row label. */
 export const INNER_TRANSITION_ROWS: ReadonlyArray<{
   row: number;