react-cheminfo 0.11.0 → 0.12.0

package/src/orbital/ui/renderVolume.ts

@@ -32,12 +32,12 @@ export interface VolumeStyle {
    * Lobe where the wavefunction is positive, as `#rrggbb`.
    * @default '#2563eb'
    */
-  positiveColour?: string;
+  positiveColor?: string;
   /**
    * Lobe where the wavefunction is negative, as `#rrggbb`.
    * @default '#dc2626'
    */
-  negativeColour?: string;
+  negativeColor?: string;
   /**
    * Isovalue as a multiple of the contour's own cutoff. Larger means a
    * tighter, smaller surface.
@@ -73,8 +73,8 @@ export async function renderSampledVolume(
     throw new Error('renderSampledVolume: the molstar canvas is not ready.');
   }
   const {
-    positiveColour = '#2563eb',
-    negativeColour = '#dc2626',
+    positiveColor = '#2563eb',
+    negativeColor = '#dc2626',
     relativeIsovalue = 1,
     alpha = 0.72,
   } = style;
@@ -95,14 +95,14 @@ export async function renderSampledVolume(
       volume,
       field.max >= cutoff ? cutoff : undefined,
       relativeIsovalue,
-      { colour: positiveColour, alpha },
+      { color: positiveColor, alpha },
     ),
     maybeSurface(
       plugin,
       volume,
       field.min <= -cutoff ? -cutoff : undefined,
       relativeIsovalue,
-      { colour: negativeColour, alpha },
+      { color: negativeColor, alpha },
     ),
   ]);
   const drawn = surfaces.filter(
@@ -143,7 +143,7 @@ export function clearSampledVolume(plugin: PluginContext): void {
  * @param isovalue - Absolute isovalue of the surface.
  * @param relativeIsovalue - Multiplier applied to it.
  * @param style - Colour and opacity of the surface.
- * @param style.colour - Surface colour, as `#rrggbb`.
+ * @param style.color - Surface colour, as `#rrggbb`.
  * @param style.alpha - Surface opacity.
  * @returns The surface representation.
  */
@@ -152,14 +152,14 @@ async function maybeSurface(
   volume: Volume,
   isovalue: number | undefined,
   relativeIsovalue: number,
-  style: { colour: string; alpha: number },
+  style: { color: string; alpha: number },
 ): Promise<Representation.Any | null> {
   if (isovalue === undefined || isovalue === 0) return null;
   return createSurface(
     plugin,
     volume,
     isovalue * relativeIsovalue,
-    style.colour,
+    style.color,
     style.alpha,
   );
 }
@@ -168,7 +168,7 @@ async function createSurface(
   plugin: PluginContext,
   volume: Volume,
   isovalue: number,
-  colour: string,
+  color: string,
   alpha: number,
 ): Promise<Representation.Any> {
   const params = createVolumeRepresentationParams(plugin, volume, {
@@ -186,7 +186,7 @@ async function createSurface(
       tryUseGpu: false,
     },
     color: 'uniform',
-    colorParams: { value: Color.fromHexStyle(colour) },
+    colorParams: { value: Color.fromHexStyle(color) },
   });
   const provider = plugin.representation.volume.registry.get(params.type.name);
   const representation = provider.factory(
@@ -204,7 +204,7 @@ async function createSurface(
 }
 
 /**
- * One pair of surfaces per plugin. They are outside the state tree, like the
- * cartoon lobes, because every change of orbital replaces them entirely.
+ * One pair of surfaces per plugin. They are outside the state tree because
+ * every change of orbital replaces them entirely.
  */
 const representations = new WeakMap<PluginContext, Representation.Any[]>();

package/src/orbital/ui/serial.ts

@@ -9,7 +9,7 @@
  */
 
 /** Runs what it is given after everything handed to it before. */
-export interface SerialRunner {
+interface SerialRunner {
   /**
    * Queue `task`, and resolve to what it returns.
    * @param task - The work to run once the queue reaches it.

package/src/orbital/ui/viewer.ts

@@ -15,9 +15,6 @@
 
 import { PluginViewModel } from 'molstar/lib/extensions/plugin/view-model.js';
 import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
-// Lowercased on import: it is a factory, not a constructor.
-import { DefaultPluginSpec as defaultPluginSpec } from 'molstar/lib/mol-plugin/spec.js';
-import { Color } from 'molstar/lib/mol-util/color/color.js';
 
 import type { OrbitalGrid } from '../core/grid.ts';
 import type { OrbitalContour } from '../core/isovalue.ts';
@@ -29,21 +26,14 @@ import {
   refitOrbital,
   setSpin,
 } from './camera.ts';
+import type { OrbitalViewerOptions } from './orbitalPluginSpec.ts';
+import { orbitalPluginSpec } from './orbitalPluginSpec.ts';
 import type { AxesStyle } from './renderAxes.ts';
 import { clearOrbitalAxes, renderOrbitalAxes } from './renderAxes.ts';
 import type { VolumeStyle } from './renderVolume.ts';
 import { clearSampledVolume, renderSampledVolume } from './renderVolume.ts';
 import { createSerialRunner } from './serial.ts';
 
-/** Settings fixed for the life of a viewer. */
-export interface OrbitalViewerOptions {
-  /**
-   * Scene background, as `#rrggbb`.
-   * @default '#ffffff'
-   */
-  background?: string;
-}
-
 /**
  * Create a viewer inside `container` and start initialising it.
  * @param container - An element with `position: relative`; molstar inserts its
@@ -77,27 +67,7 @@ export class OrbitalViewer {
   readonly ready: Promise<void>;
 
   constructor(container: HTMLElement, options: OrbitalViewerOptions = {}) {
-    const { background = '#ffffff' } = options;
-    const spec = defaultPluginSpec();
-    this.#model = new PluginViewModel({
-      spec: {
-        ...spec,
-        canvas3d: {
-          ...spec.canvas3d,
-          renderer: { backgroundColor: Color.fromHexStyle(background) },
-          camera: {
-            helper: { axes: { name: 'off', params: {} } },
-            // The camera is ours alone. Molstar reframes itself whenever a
-            // scene commit leaves the renderable count at zero, which is what
-            // replacing one orbital by another does — the old surfaces are
-            // removed and committed before the new ones exist — and it frames
-            // the whole sampled box rather than the isosurface inside it,
-            // which leaves the orbital a fifth of the frame wide.
-            manualReset: true,
-          },
-        },
-      },
-    });
+    this.#model = new PluginViewModel({ spec: orbitalPluginSpec(options) });
     this.#model.mount(container);
     this.ready = this.#model.initialized;
   }
@@ -208,9 +178,9 @@ export class OrbitalViewer {
   /**
    * Put the camera back where the orbital was first framed from.
    *
-   * The counterpart of `refit`: since a view is now kept across a change of
-   * orbital, a student who has turned the atom into an unreadable angle needs
-   * one way back.
+   * The counterpart of `refit`: the view is kept across a change of orbital,
+   * so a student who has turned the atom into an unreadable angle needs one
+   * way back.
    * @param durationMs - Transition length; 0 jumps.
    * @returns Nothing, once the camera has been set.
    */

package/src/orbital.ts

@@ -1,11 +1,12 @@
 /**
  * The molstar-backed orbital viewer.
  *
- * A third entry point, and not part of `react-cheminfo/ui`, because molstar is
+ * An entry point of its own, not part of `react-cheminfo/ui`, because molstar is
  * several megabytes: a site that only wants the Tools menu must never be made
- * to carry it. Everything here is React; the maths these components draw is in
- * `react-cheminfo/core` and needs neither React nor molstar, so a worker can
- * import it on its own.
+ * to carry it. The maths these components draw needs neither React nor molstar:
+ * it is exported here beside the viewer, and from `react-cheminfo/core` too, so
+ * a worker can import it on its own.
  */
 
+export * from './orbital/core/index.ts';
 export * from './orbital/ui/index.ts';

package/src/overlay/core/index.ts

@@ -9,7 +9,8 @@
 
 export type { EmptiestCornerOptions } from './emptiestCorner.ts';
 export { emptiestCorner } from './emptiestCorner.ts';
-export { shouldCollapseOverlay } from './overlayCollapse.ts';
+export type { OverlayBarFoldOptions } from './overlayCollapse.ts';
+export { overlayBarFolded, shouldCollapseOverlay } from './overlayCollapse.ts';
 export type { OverlayMarkShape } from './overlayMarks.ts';
 export { OVERLAY_MARK_SHAPES, isFilledMark } from './overlayMarks.ts';
 export type {

package/src/overlay/core/overlayCollapse.ts

@@ -18,3 +18,35 @@ export function shouldCollapseOverlay(
   if (!Number.isFinite(collapseBelow)) return false;
   return width < collapseBelow;
 }
+
+/** What decides whether a bar of controls is folded. */
+export interface OverlayBarFoldOptions {
+  /** What the caller asked for, when it is holding the fold itself. */
+  collapsed: boolean | undefined;
+  /** Whether the bar was asked to start folded. */
+  startedFolded: boolean;
+  /** Width of the figure, in pixels; `0` before it has been measured. */
+  width: number;
+  /** The width under which the bar folds on its own. */
+  collapseBelow: number;
+}
+
+/**
+ * Whether a bar of controls is folded.
+ *
+ * A caller holding `collapsed` is obeyed outright, so a bar driven from
+ * outside never argues with the figure's width; every other bar folds itself
+ * once the figure is too narrow, or because it was asked to start that way.
+ *
+ * It is the answer `OverlayBar` draws from, so a caller that needs to know —
+ * to word a caption for a folded bar, say — passes the same options, with the
+ * width `useOverlaySurface` reads, and gets the same answer.
+ * @param options - See {@link OverlayBarFoldOptions}.
+ * @returns Whether it is folded.
+ */
+export function overlayBarFolded(options: OverlayBarFoldOptions): boolean {
+  const { collapsed, startedFolded, width, collapseBelow } = options;
+  return (
+    collapsed ?? (startedFolded || shouldCollapseOverlay(width, collapseBelow))
+  );
+}

package/src/overlay/core/placeOverlayCard.ts

@@ -1,3 +1,5 @@
+import { clamp } from '../../format/core/clamp.ts';
+
 /** What {@link placeOverlayCard} has to know. */
 export interface OverlayCardPlacementOptions {
   /** Pointer position inside the figure, in pixels from its left. */
@@ -87,7 +89,5 @@ const DEFAULT_OFFSET = 14;
  * @returns The offset, brought back between zero and that limit.
  */
 function withinBox(value: number, furthest: number): number {
-  if (!Number.isFinite(value)) return 0;
-  const limit = Number.isFinite(furthest) ? Math.max(0, furthest) : 0;
-  return Math.max(0, Math.min(value, limit));
+  return clamp(value, 0, Number.isFinite(furthest) ? Math.max(0, furthest) : 0);
 }

package/src/overlay/ui/OverlayBar.tsx

@@ -2,11 +2,12 @@ import type { IconName } from '@blueprintjs/core';
 import type { ReactElement, ReactNode } from 'react';
 import { useState } from 'react';
 
+import { overlayBarFolded } from '../core/overlayCollapse.ts';
 import type { OverlayPlacement } from '../core/overlayPlacement.ts';
 
 import { OverlayBarCard } from './OverlayBarCard.tsx';
 import { OverlayBarStrip } from './OverlayBarStrip.tsx';
-import { overlayBarFolded, useFoldReport } from './overlayBarShape.ts';
+import type { OverlayPanel } from './OverlayPanel.tsx';
 import { OVERLAY_RESTING_OPACITY } from './overlayStyles.ts';
 import { useOverlaySurface } from './overlaySurface.ts';
 
@@ -74,7 +75,9 @@ export interface OverlayBarProps {
   /**
    * 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
-   * `collapseBelow`.
+   * `collapseBelow`. A caller that needs to know whether a bar left to decide
+   * has folded asks `overlayBarFolded` with the width `useOverlaySurface`
+   * reads, which is the answer the bar itself draws from.
    * @default undefined — the bar decides from the figure's width
    */
   collapsed?: boolean;
@@ -83,11 +86,6 @@ export interface OverlayBarProps {
    * @default false
    */
   defaultCollapsed?: boolean;
-  /**
-   * Called when the reader opens or closes it.
-   * @default undefined
-   */
-  onCollapsedChange?: (collapsed: boolean) => void;
   /**
    * Figure width, in pixels, under which the bar folds on its own.
    * @default 420
@@ -132,7 +130,7 @@ export function OverlayBar(props: OverlayBarProps): ReactElement {
   const { children, end, tools, info, more } = props;
   const { placement = 'top-right' } = props;
   const { label = 'Options', restingOpacity = OVERLAY_RESTING_OPACITY } = props;
-  const { collapsed, defaultCollapsed = false, onCollapsedChange } = props;
+  const { collapsed, defaultCollapsed = false } = props;
   const { collapseBelow = 420, moreIcon = 'cog', testId } = props;
   const { morePadded = true } = props;
   const { width } = useOverlaySurface();
@@ -144,10 +142,6 @@ export function OverlayBar(props: OverlayBarProps): ReactElement {
     width,
     collapseBelow,
   });
-  useFoldReport(
-    folded,
-    collapsed === undefined ? onCollapsedChange : undefined,
-  );
 
   if (placement === 'stretch') {
     return (

package/src/overlay/ui/OverlayBarButton.tsx

@@ -6,11 +6,12 @@ import { useState } from 'react';
 import type { OverlayPlacement } from '../core/overlayPlacement.ts';
 
 import { OverlayIconButton } from './OverlayIconButton.tsx';
+import type { OverlayPanel } from './OverlayPanel.tsx';
 import { overlayPanelStyle } from './overlayStyles.ts';
 import { useOverlaySurface } from './overlaySurface.ts';
 
 /** What {@link OverlayBarButton} opens. */
-export interface OverlayBarButtonProps {
+interface OverlayBarButtonProps {
   /**
    * The controls it holds: whatever has folded away, then the second tier —
    * everything an expert changes and a reader never does.

package/src/overlay/ui/OverlayBarCard.tsx

@@ -11,7 +11,7 @@ import {
 import { useOverlaySurface } from './overlaySurface.ts';
 
 /** What {@link OverlayBarCard} needs on top of the shape both bars share. */
-export interface OverlayBarCardProps extends OverlayBarShapeProps {
+interface OverlayBarCardProps extends OverlayBarShapeProps {
   /** How opaque the ground is while nothing is pointing at the figure. */
   restingOpacity: number;
 }

package/src/overlay/ui/OverlayChip.tsx

@@ -13,6 +13,7 @@ import {
   overlayChipStyle,
   overlayValueTextStyle,
 } from './overlayValueStyles.ts';
+import { useOverlayInteraction } from './useOverlayInteraction.ts';
 
 /** One setting a chip reads out. */
 export interface OverlayChipSetting {
@@ -78,8 +79,7 @@ export function OverlayChip(props: OverlayChipProps): ReactElement {
   const { metrics } = useOverlaySurface();
   const headingId = useId();
   const [open, setOpen] = useState(false);
-  const [hovered, setHovered] = useState(false);
-  const [focused, setFocused] = useState(false);
+  const { hovered, focused, handlers } = useOverlayInteraction();
 
   const swatches = leadingSwatches(settings);
   const name = announce(settings);
@@ -117,10 +117,7 @@ export function OverlayChip(props: OverlayChipProps): ReactElement {
           active: open,
           disabled,
         })}
-        onPointerEnter={() => setHovered(true)}
-        onPointerLeave={() => setHovered(false)}
-        onFocus={() => setFocused(true)}
-        onBlur={() => setFocused(false)}
+        {...handlers}
       >
         {swatches === undefined ? null : (
           <OverlaySwatchIcon colors={swatches} />

package/src/overlay/ui/OverlayIconButton.tsx

@@ -1,13 +1,13 @@
 import type { IconName } from '@blueprintjs/core';
 import { Icon } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
-import { useState } from 'react';
 
 import { overlayIconButtonStyle } from './overlayControlStyles.ts';
 import { useOverlaySurface } from './overlaySurface.ts';
+import { useOverlayInteraction } from './useOverlayInteraction.ts';
 
 /** What {@link OverlayIconButton} needs. */
-export interface OverlayIconButtonProps {
+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
@@ -82,7 +82,7 @@ export function OverlayIconButton(props: OverlayIconButtonProps): ReactElement {
   const { icon, label, value, active = false, disabled = false } = props;
   const { disabledReason, opensMenu = false, onClick, testId } = props;
   const { metrics } = useOverlaySurface();
-  const [lit, setLit] = useState(false);
+  const { hovered, focused, handlers } = useOverlayInteraction();
 
   const name = value === undefined ? label : `${label} — ${value}`;
   const told = disabled && disabledReason !== undefined ? disabledReason : name;
@@ -98,15 +98,13 @@ export function OverlayIconButton(props: OverlayIconButtonProps): ReactElement {
       disabled={disabled}
       data-testid={testId}
       style={overlayIconButtonStyle(metrics, {
-        hovered: lit,
+        hovered,
+        focused,
         active,
         disabled,
       })}
       onClick={onClick}
-      onPointerEnter={() => setLit(true)}
-      onPointerLeave={() => setLit(false)}
-      onFocus={() => setLit(true)}
-      onBlur={() => setLit(false)}
+      {...handlers}
     >
       {typeof icon === 'string' ? (
         <Icon icon={icon} size={glyphSize(metrics.buttonSize)} />

package/src/overlay/ui/OverlayLayer.tsx

@@ -1,6 +1,7 @@
 import type { ReactElement, ReactNode } from 'react';
 import { useEffect, useMemo, useRef, useState } from 'react';
 
+import { joinClassNames } from '../../shared/ui/joinClassNames.ts';
 import type { OverlayDensity } from '../core/overlayMetrics.ts';
 import { overlayMetrics } from '../core/overlayMetrics.ts';
 
@@ -102,9 +103,7 @@ export function OverlayLayer(props: OverlayLayerProps): ReactElement {
   return (
     <div
       ref={layer}
-      className={
-        className === undefined ? 'overlay-layer' : `overlay-layer ${className}`
-      }
+      className={joinClassNames('overlay-layer', className)}
       style={OVERLAY_LAYER_STYLE}
       data-figure="chrome"
       onFocus={() => setFocusInside(true)}

package/src/overlay/ui/OverlayLegend.tsx

@@ -1,6 +1,7 @@
 import type { CSSProperties, ReactElement } from 'react';
 import { useId } from 'react';
 
+import { formatInteger } from '../../format/core/numbers.ts';
 import type { OverlayMarkShape } from '../core/overlayMarks.ts';
 import type { OverlayMetrics } from '../core/overlayMetrics.ts';
 import type { OverlayPlacement } from '../core/overlayPlacement.ts';
@@ -183,7 +184,7 @@ function LegendEntry(props: LegendEntryProps): ReactElement {
 
 function entryLabel(entry: OverlayLegendEntry): string {
   if (entry.count === undefined) return entry.label;
-  return `${entry.label} (${entry.count.toLocaleString()})`;
+  return `${entry.label} (${formatInteger(entry.count)})`;
 }
 
 function foldStyle(metrics: OverlayMetrics): CSSProperties {

package/src/overlay/ui/OverlayNumber.tsx

@@ -1,5 +1,9 @@
 import type { KeyboardEvent, ReactElement } from 'react';
 
+import { clamp } from '../../format/core/clamp.ts';
+import { formatDecimal } from '../../format/core/numbers.ts';
+import { roundTo } from '../../format/core/roundTo.ts';
+
 import type { OverlayControlProps } from './OverlayRow.tsx';
 import { OverlayRow } from './OverlayRow.tsx';
 import {
@@ -67,7 +71,7 @@ export function OverlayNumber(props: OverlayNumberProps): ReactElement {
   const { metrics } = useOverlaySurface();
 
   function move(steps: number): void {
-    const next = clamp(value + steps * step, min, max);
+    const next = landOnRange(value + steps * step, min, max);
     if (next !== value) onChange(next);
   }
 
@@ -100,7 +104,7 @@ export function OverlayNumber(props: OverlayNumberProps): ReactElement {
           style={overlayNumberValueStyle(metrics, widestValue(props))}
           aria-live="polite"
         >
-          {`${value.toFixed(digits)}${unit}`}
+          {`${formatDecimal(value, digits)}${unit}`}
         </span>
         <button
           type="button"
@@ -128,7 +132,10 @@ export function OverlayNumber(props: OverlayNumberProps): ReactElement {
  */
 function widestValue(props: OverlayNumberProps): number {
   const { min, max, digits = 0, unit = '' } = props;
-  const ends = Math.max(min.toFixed(digits).length, max.toFixed(digits).length);
+  const ends = Math.max(
+    formatDecimal(min, digits).length,
+    formatDecimal(max, digits).length,
+  );
   return ends + unit.length;
 }
 
@@ -143,14 +150,11 @@ function widestValue(props: OverlayNumberProps): number {
  * @param max - The largest it may be.
  * @returns The value the caller is handed.
  */
-function clamp(value: number, min: number, max: number): number {
-  const rounded = Math.round(value * FLOAT_GRID) / FLOAT_GRID;
-  if (rounded < min) return min;
-  if (rounded > max) return max;
-  return rounded;
+function landOnRange(value: number, min: number, max: number): number {
+  return clamp(roundTo(value, FLOAT_GRID_DECIMALS), min, max);
 }
 
-const FLOAT_GRID = 1e10;
+const FLOAT_GRID_DECIMALS = 10;
 
 const STEPS_BY_KEY = new Map([
   ['ArrowUp', 1],

package/src/overlay/ui/OverlayPanel.tsx

@@ -1,9 +1,12 @@
 import type { ReactElement, ReactNode } from 'react';
-import { useId, useMemo, useState } from 'react';
+import { useId, useMemo } from 'react';
 
 import type { HelpContent } from '../../help/ui/HelpBody.tsx';
 import { HelpIcon } from '../../help/ui/HelpIcon.tsx';
 
+import type { OverlayAction } from './OverlayAction.tsx';
+import type { OverlayGroup } from './OverlayGroup.tsx';
+import type { OverlayRow } from './OverlayRow.tsx';
 import type { OverlayPanelShape } from './overlayPanelContext.ts';
 import { OverlayPanelContext } from './overlayPanelContext.ts';
 import {
@@ -17,6 +20,7 @@ import {
 } from './overlayPanelStyles.ts';
 import { overlayNameColumnWidth } from './overlayRowStyles.ts';
 import { useOverlaySurface } from './overlaySurface.ts';
+import { useOverlayInteraction } from './useOverlayInteraction.ts';
 
 /** What {@link OverlayPanel} holds. */
 export interface OverlayPanelProps {
@@ -101,7 +105,7 @@ export function OverlayPanel(props: OverlayPanelProps): ReactElement {
   const { actions, hint = DEFAULT_HINT, nameWidth, testId } = props;
   const { metrics } = useOverlaySurface();
   const titleId = useId();
-  const [resetHovered, setResetHovered] = useState(false);
+  const reset = useOverlayInteraction();
 
   const width = nameWidth ?? overlayNameColumnWidth(metrics);
   const shape = useMemo<OverlayPanelShape>(
@@ -126,12 +130,9 @@ export function OverlayPanel(props: OverlayPanelProps): ReactElement {
         {onReset === undefined ? null : (
           <button
             type="button"
-            style={overlayPanelResetStyle(metrics, resetHovered)}
+            style={overlayPanelResetStyle(metrics, reset)}
             onClick={onReset}
-            onPointerEnter={() => setResetHovered(true)}
-            onPointerLeave={() => setResetHovered(false)}
-            onFocus={() => setResetHovered(true)}
-            onBlur={() => setResetHovered(false)}
+            {...reset.handlers}
           >
             {resetLabel}
           </button>

package/src/overlay/ui/OverlayRow.tsx

@@ -4,6 +4,10 @@ import { useId } from 'react';
 import type { HelpContent } from '../../help/ui/HelpBody.tsx';
 import { HelpTooltip } from '../../help/ui/HelpTooltip.tsx';
 
+import type { OverlayBar } from './OverlayBar.tsx';
+import type { OverlayPanel } from './OverlayPanel.tsx';
+import type { OverlaySegmented } from './OverlaySegmented.tsx';
+import type { OverlaySelect } from './OverlaySelect.tsx';
 import { useOverlayPanelShape } from './overlayPanelContext.ts';
 import {
   OVERLAY_GRID_CELL_STYLE,
@@ -119,8 +123,8 @@ export interface OverlayRowProps extends OverlayControlProps {
  * word; a dotted underline says the same thing and costs nothing. The name is
  * reachable by tab for the same reason the glyph was, so the explanation is
  * not reserved to whoever is holding a pointer, and it carries the class
- * `help-name` — the counterpart of the glyph's `help-icon` — so that whatever
- * used to look for the glyph has something to look for. In a panel the name
+ * `help-name` — the counterpart of the glyph's `help-icon` — so that a style
+ * or a test looking for either has something to find. In a panel the name
  * also names its row out loud, since a name a whole column away from its
  * control is not associated with it by proximity alone.
  * @param props - See {@link OverlayRowProps}.

package/src/overlay/ui/OverlayToggle.tsx

@@ -2,6 +2,7 @@ import type { IconName } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
 import { Button } from 'react-science/ui';
 
+import type { OverlayPanel } from './OverlayPanel.tsx';
 import type { OverlayControlProps } from './OverlayRow.tsx';
 import { OverlayRow } from './OverlayRow.tsx';
 import { overlaySwatchStyle } from './overlayControlStyles.ts';

package/src/overlay/ui/OverlayValueButton.tsx

@@ -1,6 +1,5 @@
 import { Icon } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
-import { useState } from 'react';
 
 import { OverlaySwatchIcon } from './OverlaySwatchIcon.tsx';
 import { useOverlaySurface } from './overlaySurface.ts';
@@ -10,6 +9,7 @@ import {
   overlayValueKeyStyle,
   overlayValueTextStyle,
 } from './overlayValueStyles.ts';
+import { useOverlayInteraction } from './useOverlayInteraction.ts';
 
 /** What {@link OverlayValueButton} needs. */
 export interface OverlayValueButtonProps {
@@ -81,9 +81,8 @@ export interface OverlayValueButtonProps {
 /**
  * A setting written as its own value, with a caret saying it can be changed.
  *
- * It replaces the two idioms a bar used to hold for the same job — a caption
- * beside an outlined segmented control, and a caption beside a native select —
- * with one that costs no box at all. The reader scans the bar and reads
+ * It does the job of a caption beside a segmented control or a native select
+ * at the cost of no box at all. The reader scans the bar and reads
  * `Species` and `95%`, which is how the figure is drawn; the names of the two
  * settings are one press away and in every announcement.
  * @param props - See {@link OverlayValueButtonProps}.
@@ -96,8 +95,7 @@ export function OverlayValueButton(
   const { active = false, disabled = false, disabledReason } = props;
   const { opensMenu = false, onClick, testId } = props;
   const { metrics } = useOverlaySurface();
-  const [hovered, setHovered] = useState(false);
-  const [focused, setFocused] = useState(false);
+  const { hovered, focused, handlers } = useOverlayInteraction();
 
   const name = `${label} — ${value}`;
   const told = disabled && disabledReason !== undefined ? disabledReason : name;
@@ -118,10 +116,7 @@ export function OverlayValueButton(
         disabled,
       })}
       onClick={onClick}
-      onPointerEnter={() => setHovered(true)}
-      onPointerLeave={() => setHovered(false)}
-      onFocus={() => setFocused(true)}
-      onBlur={() => setFocused(false)}
+      {...handlers}
     >
       {swatches === undefined || swatches.length === 0 ? null : (
         <OverlaySwatchIcon colors={swatches} />