react-cheminfo 0.45.0 → 0.47.0

package/src/chart/core/chartDomain.ts

@@ -80,18 +80,29 @@ export const DEFAULT_Y_AXIS_RULES: Required<YAxisRules> = {
  * between forty and sixty percent", so a drag narrows the horizontal axis and
  * leaves the height alone unless it is released past the baseline.
  *
+ * `dual` is the same reading gesture with a gate a reader can predict: a drag
+ * kept level narrows the horizontal axis alone, and one taken far enough up or
+ * down brings the height with it. It is what `xAxis` cannot be on a chart whose
+ * vertical axis has no baseline to cross — a titration curve climbing from pH 2
+ * to pH 12, a speciation diagram drawn over decades — where "has the pointer
+ * passed zero" is a question about the margin rather than about the data, and
+ * the answer to it is no for every drag made inside the plot. Here both windows
+ * are asked for where the curve is, and the preview changes shape as the
+ * threshold is crossed, so the rectangle is found by the hand that was already
+ * drawing one.
+ *
  * `box` is the tool: while it is chosen, the rectangle dragged out is the window,
  * both axes at once. It is a mode rather than a modifier because it is used in
  * runs — a baseline being examined is examined several times over — and a
  * modifier held down through each of them is a worse gesture than a tool pressed
  * once.
  *
- * The two are named apart from the whole of `DragMode` so that a chart offering
- * nothing but zoom tools can say so in its own signature — which is what stops
- * `select`, the one drag that moves no axis, from reaching a chart with no
- * handler for it.
+ * The three are named apart from the whole of `DragMode` so that a chart
+ * offering nothing but zoom tools can say so in its own signature — which is
+ * what stops `select`, the one drag that moves no axis, from reaching a chart
+ * with no handler for it.
  */
-export type ZoomDragMode = 'xAxis' | 'box';
+export type ZoomDragMode = 'xAxis' | 'dual' | 'box';
 
 /**
  * What a drag across the plot asks for.
@@ -152,12 +163,27 @@ export interface ZoomGestures {
    * @default true
    */
   wheel?: boolean;
+  /**
+   * Whether the chart answers `f` with a window fitted to everything drawn.
+   *
+   * The same thing the double click does, reachable without a pointer — and the
+   * one gesture a reader cannot discover by trying, which is why the key is the
+   * same `f` on every chart of the family rather than each one choosing.
+   *
+   * Turned off by a viewer that already owns its keys: the infrared shell runs
+   * `f` through its own command table, where the key is listed in a toolbar
+   * tooltip and in the documentation panel, and fits every pane of a stack
+   * rather than the one chart the pointer is on.
+   * @default true
+   */
+  keys?: boolean;
 }
 
 /** What the gestures come to when a viewer states none of them. */
 export const DEFAULT_ZOOM_GESTURES: Required<ZoomGestures> = {
   drag: 'xAxis',
   wheel: true,
+  keys: true,
 };
 
 /**

package/src/chart/core/index.ts

@@ -169,7 +169,9 @@ export {
 } from './viewTransform.ts';
 export type { DragBox, ZoomSelection } from './zoomDomain.ts';
 export {
+  DUAL_ZOOM_TRAVEL,
   MINIMUM_DRAG,
+  draggedBeyondLevel,
   releasedBeyondBaseline,
   scaledYAxis,
   zoomSelection,

package/src/chart/core/selectionGeometry.ts

@@ -31,12 +31,15 @@ export interface SelectionRectangle {
 /**
  * The rectangle to draw for a drag being made.
  *
- * A drag that takes the y axis with it is drawn at the height of the drag
- * itself, and one that asks for the x axis alone spans the whole plot.
+ * A drag that takes the y axis with it is drawn at the height `zoomSelection`
+ * worked out — the window the release will take, which is the drag's own height
+ * stretched to any baseline the viewer holds — and one that asks for the x axis
+ * alone spans the whole plot.
  * That is the gesture announcing itself before the button is let go: the
- * rectangle changing shape as the pointer crosses the baseline is the only
- * warning a user gets that the release is about to move both axes, and it is one
- * they can still act on.
+ * rectangle changing shape — as the pointer crosses the baseline, or as a
+ * `dual` drag leaves the level it started on — is the only warning a user gets
+ * that the release is about to move both axes, and it is one they can still act
+ * on.
  *
  * A drag too short to zoom draws nothing at all. Below `MINIMUM_DRAG` the
  * release does nothing — most clicks made on a trackpad wobble by a pixel or two

package/src/chart/core/zoomDomain.ts

@@ -10,7 +10,7 @@
 
 import { clamp } from '../../format/core/clamp.ts';
 
-import type { ChartDomain, ZoomRules } from './chartDomain.ts';
+import type { ChartDomain, DragMode, ZoomRules } from './chartDomain.ts';
 import { DEFAULT_Y_AXIS_RULES } from './chartDomain.ts';
 import type { PlotRect } from './chartGeometry.ts';
 import type { ChartScale } from './chartScale.ts';
@@ -30,6 +30,19 @@ import { chartPixel, chartValue } from './chartScale.ts';
  */
 export const MINIMUM_DRAG = 4;
 
+/**
+ * How far a `dual` drag has to travel vertically before it brings the y axis
+ * with it, in user units of the SVG.
+ *
+ * Far enough above `MINIMUM_DRAG` that no drag meant to stay level reaches it by
+ * the tremor of a hand or the slope of a trackpad swipe, and near enough that
+ * the rectangle a reader wants costs one gesture rather than a reach for the
+ * margin. The preview changes shape on the pixel it is crossed, so the number
+ * itself never has to be learnt: the first drag that crosses it teaches the
+ * gesture, and the first that recrosses it back shows the way out.
+ */
+export const DUAL_ZOOM_TRAVEL = 24;
+
 /** The two corners of a drag, in the user units of the SVG. */
 export interface DragBox {
   /** Where the press landed, horizontally. */
@@ -42,7 +55,17 @@ export interface DragBox {
   toY: number;
 }
 
-/** The drag as it is being made, for the preview rectangle to be drawn from. */
+/**
+ * The drag as it is being made, for the preview rectangle to be drawn from.
+ *
+ * Its **vertical corners are the window the release will take**, not the two
+ * places the hand passed through. The two differ by the baseline a viewer's
+ * rules hold: on a mirrored chart zero runs across the middle of the plot, so a
+ * drag made wholly inside the reflected half crosses the baseline without ever
+ * reaching it, and the release stretches the window back to zero. A rectangle
+ * drawn at the height of the hand would promise a band between two intensities
+ * that letting go does not give.
+ */
 export interface ZoomSelection extends DragBox {
   /**
    * Whether letting go here would take the y axis with it, which is what the
@@ -58,9 +81,9 @@ export interface ZoomSelection extends DragBox {
  * than by the rectangle itself — so what the preview promises and what letting
  * go actually does are the same test rather than two that have to agree.
  *
- * A `select` drag is therefore always a band, however far past the baseline it
- * strays: its answer is two numbers on one axis, so a preview that grew into a
- * rectangle would promise a height nobody is ever told about.
+ * Which answer a mode gives is `takesYAxis`'s business, so a `select` drag is
+ * always a band however far past the baseline it strays, and a `dual` drag
+ * becomes a rectangle the moment it has travelled `DUAL_ZOOM_TRAVEL`.
  * @param drag - The drag being made, `null` when none is.
  * @param yScale - The y axis as it is currently zoomed.
  * @param rules - How the y axis behaves and what a drag means, defaulting to a
@@ -75,24 +98,41 @@ export function zoomSelection(
   if (drag === null) return null;
   const {
     baseline = DEFAULT_Y_AXIS_RULES.baseline,
+    keepBaseline = DEFAULT_Y_AXIS_RULES.keepBaseline,
     pointsDown = DEFAULT_Y_AXIS_RULES.pointsDown,
     drag: mode = 'xAxis',
   } = rules;
+  const zoomsYAxis = takesYAxis(drag, mode, yScale, baseline, pointsDown);
+  // Stretched in pixels rather than in values because the rectangle is drawn in
+  // pixels and the mapping is monotonic, so including the baseline's own pixel
+  // in the span is including the baseline in the window.
+  const held = zoomsYAxis && holdsBaseline(mode, keepBaseline);
+  const atBaseline = chartPixel(yScale, baseline);
   return {
     fromX: drag.fromX,
-    fromY: drag.fromY,
+    fromY: held ? Math.min(drag.fromY, drag.toY, atBaseline) : drag.fromY,
     toX: drag.toX,
-    toY: drag.toY,
-    // The box tool takes the height always, so the preview is a rectangle from
-    // the first pixel of the gesture rather than a full-height band that
-    // suddenly becomes one; a select drag never takes it at all.
-    zoomsYAxis:
-      mode === 'box' ||
-      (mode !== 'select' &&
-        releasedBeyondBaseline(drag.toY, yScale, baseline, pointsDown)),
+    toY: held ? Math.max(drag.fromY, drag.toY, atBaseline) : drag.toY,
+    zoomsYAxis,
   };
 }
 
+/**
+ * Whether a drag has left the level it started on by enough to ask for the y
+ * axis as well.
+ *
+ * Measured as the hand made it, before any clamping to the plot: a drag that ran
+ * out over the tick labels travelled however far it travelled. Nothing is
+ * latched — the answer is read off the two corners and nothing else — so a
+ * reader who drifted down and came back up is promised a band again, and the
+ * preview says so while the button is still down.
+ * @param drag - The drag being made or released, in user units of the SVG.
+ * @returns Whether the height comes along.
+ */
+export function draggedBeyondLevel(drag: DragBox): boolean {
+  return Math.abs(drag.toY - drag.fromY) >= DUAL_ZOOM_TRAVEL;
+}
+
 /**
  * Whether a drag let go here asks for the y axis as well.
  *
@@ -178,24 +218,19 @@ export function zoomedDomain(
     Math.min(firstX, secondX),
     Math.max(firstX, secondX),
   ];
-  // The box tool is asked for the rectangle it was given, wherever it was let
-  // go; the reading gesture takes the height only when it crossed the baseline.
-  if (
-    mode !== 'box' &&
-    !releasedBeyondBaseline(drag.toY, yScale, baseline, pointsDown)
-  ) {
+  if (!takesYAxis(drag, mode, yScale, baseline, pointsDown)) {
     return { x, y: current.y };
   }
 
   const fromY = chartValue(yScale, clamp(drag.fromY, plot.top, plot.bottom));
   const toY = chartValue(yScale, clamp(drag.toY, plot.top, plot.bottom));
   // Both ends, so a baseline the data runs *down* from — 100 percent
-  // transmittance — is kept as surely as one it stands on. The box tool holds no
-  // baseline at all: a rectangle dragged round a feature is a promise about
-  // exactly that rectangle, and a viewer whose axis rules keep its baseline
-  // would otherwise see the tool quietly return a taller window than the one
-  // drawn.
-  const holdBaseline = keepBaseline && mode !== 'box';
+  // transmittance — is kept as surely as one it stands on. Only the reading
+  // gesture holds a baseline: a rectangle dragged out deliberately, by the box
+  // tool or by a `dual` drag that left its level, is a promise about exactly
+  // that rectangle, and a viewer whose axis rules keep its baseline would
+  // otherwise see a taller window than the one drawn.
+  const holdBaseline = holdsBaseline(mode, keepBaseline);
   const bottom = holdBaseline
     ? Math.min(baseline, fromY, toY)
     : Math.min(fromY, toY);
@@ -233,3 +268,51 @@ export function scaledYAxis(
   ];
   return y[1] > y[0] ? { x: current.x, y } : current;
 }
+
+/**
+ * Whether a drag brings the y axis with it, which is the one question the
+ * preview and the release must never answer differently.
+ *
+ * Asked once, here, rather than by each of them: a rectangle that promises a
+ * height the release then refuses teaches a reader that the chart is
+ * unreliable, and two copies of this test are how that comes about.
+ *
+ * The box tool takes the height always, so its preview is a rectangle from the
+ * first pixel of the gesture rather than a full-height band that suddenly
+ * becomes one. A `select` drag never takes it at all: its answer is two numbers
+ * on one axis, and a preview that grew into a rectangle would promise a height
+ * nobody is ever told about.
+ * @param drag - The drag being made or released, in user units of the SVG.
+ * @param mode - What a drag on this chart asks for.
+ * @param yScale - The y axis as it is currently zoomed.
+ * @param baseline - The value the reading gesture is judged against.
+ * @param pointsDown - Whether the data hangs below that baseline.
+ * @returns Whether the height comes along.
+ */
+/**
+ * Whether the window keeps the baseline whatever the drag asked for, which the
+ * preview and the release must agree on as surely as they agree on the height.
+ *
+ * Only the reading gesture holds it. A rectangle dragged out deliberately — by
+ * the box tool, or by a `dual` drag that left its level — is a promise about
+ * exactly that rectangle.
+ * @param mode - What a drag on this chart asks for.
+ * @param keepBaseline - Whether the viewer's rules keep it.
+ * @returns Whether the baseline stays in the window.
+ */
+function holdsBaseline(mode: DragMode, keepBaseline: boolean): boolean {
+  return keepBaseline && mode === 'xAxis';
+}
+
+function takesYAxis(
+  drag: DragBox,
+  mode: DragMode,
+  yScale: ChartScale,
+  baseline: number,
+  pointsDown: boolean,
+): boolean {
+  if (mode === 'box') return true;
+  if (mode === 'select') return false;
+  if (mode === 'dual') return draggedBeyondLevel(drag);
+  return releasedBeyondBaseline(drag.toY, yScale, baseline, pointsDown);
+}

package/src/chart/ui/SelectionRect.tsx

@@ -36,6 +36,10 @@ export function SelectionRect(props: SelectionRectProps): ReactElement | null {
 
   return (
     <rect
+      // Named, because the shape of this rectangle is the whole promise a drag
+      // makes — a band for the x axis alone, the drawn height for both — and
+      // the only way to check the promise is to measure it mid-drag.
+      data-testid="chart-selection"
       x={rectangle.x}
       y={rectangle.y}
       width={rectangle.width}

package/src/chart/ui/chartGestures.ts

@@ -14,8 +14,12 @@
  * gesture reporting a range and a click for the same drag.
  */
 
-import type { PointerEvent as ReactPointerEvent } from 'react';
+import type {
+  KeyboardEvent as ReactKeyboardEvent,
+  PointerEvent as ReactPointerEvent,
+} from 'react';
 
+import { isEditingField } from '../../panel/core/isEditingField.ts';
 import type { ChartDomain, ZoomRules } from '../core/chartDomain.ts';
 import type { PlotRect } from '../core/chartGeometry.ts';
 import type { ChartScale } from '../core/chartScale.ts';
@@ -29,6 +33,7 @@ import { isInsidePlot } from './useChartPointer.ts';
 
 /** One gesture on the SVG, as React hands it over. */
 type PointerHandler = (event: ReactPointerEvent<SVGSVGElement>) => void;
+type KeyboardHandler = (event: ReactKeyboardEvent<SVGSVGElement>) => void;
 
 /**
  * Which keys were held as a click was let go.
@@ -56,6 +61,41 @@ export interface ChartZoomHandlers {
   onPointerUp: PointerHandler;
   onPointerCancel: PointerHandler;
   onDoubleClick: () => void;
+  onKeyDown: KeyboardHandler;
+  /**
+   * So the chart can hold the caret, which is what lets a key reach it.
+   *
+   * In the tab order rather than merely focusable by a click, because the chart
+   * is* the widget here: a reader who navigates by keyboard has no other way to
+   * reach it, and a chart nobody can focus answers no key at all. A viewer that
+   * answers none takes itself back out of the order.
+   */
+  tabIndex: number;
+}
+
+/** The key that fits the window to everything drawn, on every chart. */
+export const FIT_KEY = 'f';
+
+/**
+ * Whether a key press asks for the window to be fitted.
+ *
+ * A key pressed with a modifier belongs to the browser or to the page — Ctrl+F
+ * is a search, and a chart that swallowed it to fit itself would be a chart
+ * people stop typing near — and a key delivered to a field is part of what is
+ * being written. Compared case-insensitively, so a capital arriving from a held
+ * shift still fits.
+ * @param event - The key press, as React delivers it or as the DOM does.
+ * @returns Whether the chart should fit its window.
+ */
+export function asksToFit(
+  event: Pick<
+    KeyboardEvent,
+    'key' | 'ctrlKey' | 'metaKey' | 'altKey' | 'target'
+  >,
+): boolean {
+  if (event.ctrlKey || event.metaKey || event.altKey) return false;
+  if (isEditingField(event.target)) return false;
+  return event.key.toLowerCase() === FIT_KEY;
 }
 
 /** What a host asks to be told, beyond the window it is shown anyway. */

package/src/chart/ui/index.ts

@@ -47,7 +47,7 @@ export { SelectionRect } from './SelectionRect.tsx';
 export type { LegendEntry, TraceLegendProps } from './TraceLegend.tsx';
 export { TraceLegend } from './TraceLegend.tsx';
 export type { ChartClickModifiers } from './chartGestures.ts';
-export { NO_MODIFIERS } from './chartGestures.ts';
+export { FIT_KEY, NO_MODIFIERS, asksToFit } from './chartGestures.ts';
 export { chartSurfaceStyle } from './chartSurface.ts';
 export type { ChartPointer, ChartPointerOptions } from './useChartPointer.ts';
 export {

package/src/chart/ui/useChartZoom.ts

@@ -28,7 +28,11 @@
  * answer each viewer hands over.
  */
 
-import type { PointerEvent as ReactPointerEvent, RefObject } from 'react';
+import type {
+  KeyboardEvent as ReactKeyboardEvent,
+  PointerEvent as ReactPointerEvent,
+  RefObject,
+} from 'react';
 import { useCallback, useMemo, useState } from 'react';
 
 import type {
@@ -50,6 +54,7 @@ import type {
 } from './chartGestures.ts';
 import {
   answeredRelease,
+  asksToFit,
   draggedTo,
   releaseDrag,
   startedDrag,
@@ -147,6 +152,7 @@ export function useChartZoom(options: ChartZoomOptions): ChartZoom {
   const pointsDown = yAxis?.pointsDown;
   const dragMode = gestures?.drag ?? DEFAULT_ZOOM_GESTURES.drag;
   const wheel = gestures?.wheel ?? DEFAULT_ZOOM_GESTURES.wheel;
+  const keys = gestures?.keys ?? DEFAULT_ZOOM_GESTURES.keys;
   const rules = useMemo<ZoomRules>(
     () => ({ baseline, keepBaseline, pointsDown, drag: dragMode }),
     [baseline, keepBaseline, pointsDown, dragMode],
@@ -236,6 +242,19 @@ export function useChartZoom(options: ChartZoomOptions): ChartZoom {
     [drag, yScale, rules],
   );
 
+  const onKeyDown = useCallback(
+    (event: ReactKeyboardEvent<SVGSVGElement>) => {
+      if (!keys || !asksToFit(event)) return;
+      // Taken rather than passed on, so the page under a chart does not scroll
+      // to its own next heading as well — and so a second chart mounted beside
+      // this one is not fitted by a key aimed at this one.
+      event.preventDefault();
+      event.stopPropagation();
+      reset();
+    },
+    [keys, reset],
+  );
+
   return {
     domain,
     xScale,
@@ -248,6 +267,11 @@ export function useChartZoom(options: ChartZoomOptions): ChartZoom {
       onPointerUp,
       onPointerCancel,
       onDoubleClick: reset,
+      onKeyDown,
+      // Out of the tab order again on a chart that answers no key: a stop on the
+      // way through a page that does nothing when it is reached is worse than no
+      // stop at all.
+      tabIndex: keys ? 0 : -1,
     },
   };
 }

package/src/ir/core/irMode.ts

@@ -168,7 +168,12 @@ export function zoomGestures(
   tool: ZoomDragMode = 'xAxis',
 ): Required<ZoomGestures> {
   const { boxZoomOnly, wheelZoom } = IR_MODE_RULES[mode];
-  return { drag: boxZoomOnly ? 'box' : tool, wheel: wheelZoom };
+  // The shell owns `f`: its own command table runs `resetDomain`, which fits
+  // every pane of a stack rather than the one chart the caret is in, and the key
+  // is written down in a toolbar tooltip and in the documentation panel. A chart
+  // answering it as well would fit one pane and swallow the key before the
+  // shell heard it.
+  return { drag: boxZoomOnly ? 'box' : tool, wheel: wheelZoom, keys: false };
 }
 
 /**

package/src/locales/de.json

@@ -266,6 +266,7 @@
   "periodic.table": "Periodensystem",
   "periodic.group": "Gruppe {group}",
   "periodic.period": "Periode {period}",
+  "periodic.allElements": "Alle Elemente",
   "periodic.cellLabel": "{name} ({symbol}, Z = {atomicNumber})",
   "periodic.category.alkali-metal": "Alkalimetall",
   "periodic.category.alkaline-earth-metal": "Erdalkalimetall",

package/src/locales/en.json

@@ -412,6 +412,7 @@
   "periodic.table": "Periodic table",
   "periodic.group": "Group {group}",
   "periodic.period": "Period {period}",
+  "periodic.allElements": "All elements",
   "periodic.cellLabel": "{name} ({symbol}, Z = {atomicNumber})",
   "periodic.category.alkali-metal": "Alkali metal",
   "periodic.category.alkaline-earth-metal": "Alkaline earth",

package/src/locales/es.json

@@ -266,6 +266,7 @@
   "periodic.table": "Tabla periódica",
   "periodic.group": "Grupo {group}",
   "periodic.period": "Periodo {period}",
+  "periodic.allElements": "Todos los elementos",
   "periodic.cellLabel": "{name} ({symbol}, Z = {atomicNumber})",
   "periodic.category.alkali-metal": "Metal alcalino",
   "periodic.category.alkaline-earth-metal": "Alcalinotérreo",

package/src/locales/fr.json

@@ -266,6 +266,7 @@
   "periodic.table": "Tableau périodique",
   "periodic.group": "Groupe {group}",
   "periodic.period": "Période {period}",
+  "periodic.allElements": "Tous les éléments",
   "periodic.cellLabel": "{name} ({symbol}, Z = {atomicNumber})",
   "periodic.category.alkali-metal": "Métal alcalin",
   "periodic.category.alkaline-earth-metal": "Alcalino-terreux",

package/src/locales/it.json

@@ -412,6 +412,7 @@
   "periodic.table": "Tavola periodica",
   "periodic.group": "Gruppo {group}",
   "periodic.period": "Periodo {period}",
+  "periodic.allElements": "Tutti gli elementi",
   "periodic.cellLabel": "{name} ({symbol}, Z = {atomicNumber})",
   "periodic.category.alkali-metal": "Metallo alcalino",
   "periodic.category.alkaline-earth-metal": "Alcalino terroso",

package/src/periodic/core/index.ts

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

package/src/periodic/core/layout.ts

@@ -28,6 +28,18 @@ export interface ElementRange {
   additive: boolean;
 }
 
+/** One element, and what the click that picked it asked for. */
+export interface ElementPick {
+  /**
+   * Whether the click asked for this element on top of what was already
+   * chosen — Cmd on a Mac, Ctrl elsewhere — rather than in place of it. A tool
+   * whose plain click already means something of its own — reading one element
+   * into a card — tells the two apart by it, so one table both reads an
+   * element and builds a set of them.
+   */
+  additive: boolean;
+}
+
 /** A cell of the grid, one-based as CSS grid lines are. */
 export interface Cell {
   /** Grid column, one-based. */

package/src/periodic/ui/ElementCell.tsx

@@ -16,6 +16,7 @@ import { useState } from 'react';
 
 import type { Swatch } from '../../color/core/interpolate.ts';
 import { useChromeT } from '../../i18n/ui/useT.ts';
+import type { ElementPick } from '../core/layout.ts';
 
 import {
   SHELLS_AIR,
@@ -53,8 +54,11 @@ export interface ElementCellProps {
   column: number;
   /** Row of the grid, one-based. */
   row: number;
-  /** Called with the symbol when the cell is chosen. */
-  onSelect: (symbol: string) => void;
+  /**
+   * Called with the symbol when the cell is chosen, and with what the click
+   * asked for: a plain one, or an additive one — Cmd or Ctrl held.
+   */
+  onSelect: (symbol: string, pick: ElementPick) => void;
   /**
    * Third line, under the symbol: the value the tool is showing.
    * @default '' — nothing is written
@@ -143,8 +147,8 @@ export function ElementCell(props: ElementCellProps): ReactElement {
         atomicNumber,
       })}
       aria-pressed={isSelected}
-      onClick={() => {
-        onSelect(symbol);
+      onClick={(event) => {
+        onSelect(symbol, { additive: event.metaKey || event.ctrlKey });
       }}
       onPointerEnter={() => {
         setIsHovered(true);

package/src/periodic/ui/PeriodicTable.tsx

@@ -23,7 +23,7 @@ import { useResizeObserver } from '../../hooks/ui/useResizeObserver.ts';
 import { useChromeT } from '../../i18n/ui/useT.ts';
 import { categorySwatch } from '../core/categories.ts';
 import type { PeriodicElement } from '../core/elements.ts';
-import type { ElementRange } from '../core/layout.ts';
+import type { ElementPick, ElementRange } from '../core/layout.ts';
 import {
   COLUMN_COUNT,
   EMPTY_BLOCK,
@@ -55,10 +55,12 @@ export interface PeriodicTableProps {
   selected?: string;
   /**
    * Called with the symbol of the element that was clicked, and by the arrow
-   * keys.
+   * keys. The pick says whether the click was additive — Cmd or Ctrl held — so
+   * a tool whose plain click already reads one element into a card can let the
+   * same table build a set of them.
    * @default undefined — the table is a figure rather than a control
    */
-  onSelect?: (symbol: string) => void;
+  onSelect?: (symbol: string, pick: ElementPick) => void;
   /**
    * The colour each cell takes.
    * @default the family colour
@@ -112,6 +114,13 @@ export interface PeriodicTableProps {
    * @default undefined
    */
   onSelectRange?: (range: ElementRange) => void;
+  /**
+   * Called when the corner where the two header strips meet is clicked, which
+   * is how a reader takes the whole table back. Without it the corner stays
+   * empty.
+   * @default undefined
+   */
+  onSelectAll?: () => void;
   /**
    * Whether to draw the family legend under the grid.
    * @default false
@@ -158,6 +167,7 @@ export function PeriodicTable(props: PeriodicTableProps): ReactElement {
     inset,
     headers = false,
     onSelectRange,
+    onSelectAll,
     legend = false,
     markers = true,
     keyboard = true,
@@ -198,7 +208,7 @@ export function PeriodicTable(props: PeriodicTableProps): ReactElement {
     if (next === null) return;
     event.preventDefault();
     cameFromKeyRef.current = true;
-    onSelect(next.symbol);
+    onSelect(next.symbol, PLAIN_PICK);
   }
 
   // One size for the whole table rather than one per cell: a column of values
@@ -228,7 +238,12 @@ export function PeriodicTable(props: PeriodicTableProps): ReactElement {
         style={gridStyle(headers)}
         onKeyDown={handleKeyDown}
       >
-        {headers ? <HeaderStrips onSelectRange={onSelectRange} /> : null}
+        {headers ? (
+          <HeaderStrips
+            onSelectRange={onSelectRange}
+            onSelectAll={onSelectAll}
+          />
+        ) : null}
         {inset === undefined ? null : (
           <div style={insetStyle(offset)}>{inset}</div>
         )}
@@ -290,6 +305,9 @@ function defaultNameOf(element: PeriodicElement): string {
   return element.name;
 }
 
+/** The arrow keys walk the table to read it; they never add to a set. */
+const PLAIN_PICK: ElementPick = { additive: false };
+
 function noop(): void {
   // A table with no `onSelect` is a figure; its cells stay buttons so the
   // keyboard and a screen reader still reach every element.