react-cheminfo 0.46.0 → 0.47.0

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.

package/src/periodic/ui/PeriodicTableChrome.tsx

@@ -24,18 +24,28 @@ interface HeaderStripsProps {
    * @default undefined
    */
   onSelectRange?: (range: ElementRange) => void;
+  /**
+   * Called when the corner where the two strips meet is clicked. The corner of
+   * a spreadsheet takes everything, and a table whose rows and columns are one
+   * click each owes the same for the whole of it. Without it the corner stays
+   * empty.
+   * @default undefined
+   */
+  onSelectAll?: () => void;
 }
 
 /**
- * The 1–18 strip along the top and the 1–7 strip down the left.
+ * The 1–18 strip along the top, the 1–7 strip down the left, and the corner
+ * where they meet.
  *
  * They are buttons when the table takes a range: "plot period 3" is one click
- * there and eight on the cells.
+ * there and eight on the cells. The corner takes the whole table, which is the
+ * gesture a spreadsheet has taught everybody.
  * @param props - See {@link HeaderStripsProps}.
- * @returns The two strips, placed on the grid.
+ * @returns The two strips, the corner, and the inner-transition period numbers.
  */
 export function HeaderStrips(props: HeaderStripsProps): ReactElement {
-  const { onSelectRange } = props;
+  const { onSelectRange, onSelectAll } = props;
   const t = useChromeT();
   const groups: ReactElement[] = [];
   for (let group = 1; group <= COLUMN_COUNT; group++) {
@@ -84,6 +94,19 @@ export function HeaderStrips(props: HeaderStripsProps): ReactElement {
 
   return (
     <>
+      {onSelectAll === undefined ? null : (
+        <HeaderCell
+          // The glyph points into the grid it takes, as a spreadsheet's does.
+          // It is a mark rather than a word because the corner is a
+          // seventeenth of the table's width, and the word differs in every
+          // language the chrome speaks.
+          label="◢"
+          title={t('periodic.allElements')}
+          column={1}
+          row={1}
+          onClick={onSelectAll}
+        />
+      )}
       {groups}
       {periods}
       {INNER_TRANSITION_ROWS.map(({ row, period }) => (
@@ -159,6 +182,7 @@ function HeaderCell(props: HeaderCellProps): ReactElement {
     <button
       type="button"
       aria-label={title}
+      title={title}
       onClick={onClick}
       style={{ ...style, ...headerButtonStyle }}
     >

package/src/split/ui/SplitColumn.tsx

@@ -0,0 +1,36 @@
+/**
+ * Two figures one above the other, with a splitter between them and the share
+ * each takes written into the address.
+ *
+ * The body is `splitPanes.tsx`, which `<SplitRow>` shares; its header is where
+ * the design is written down.
+ */
+
+import type { ReactElement } from 'react';
+
+import type { SplitPanesProps } from './splitPanes.tsx';
+import { SplitPanes } from './splitPanes.tsx';
+
+/**
+ * Props of {@link SplitColumn}. `start` is the top pane, `end` the bottom one,
+ * and `stackBelow` a height.
+ */
+export type SplitColumnProps = SplitPanesProps;
+
+/**
+ * Two panes sharing a column, divided where the address says.
+ *
+ * **A share needs a height to be a share of.** Put this inside a box that has
+ * one — a workbench pane, a page that fills the viewport — not inside an
+ * ordinary page column, whose height is whatever its content comes to. Given
+ * no height to divide, it measures nothing, says nothing about it, and simply
+ * stacks the two panes with no splitter, which is what an ordinary page wanted
+ * anyway.
+ *
+ * @param props - See {@link SplitColumnProps}.
+ * @returns The two panes with the splitter between them, the two stacked where
+ * there is no height to divide, or whichever one a link left, alone.
+ */
+export function SplitColumn(props: SplitColumnProps): ReactElement | null {
+  return <SplitPanes direction="vertical" {...props} />;
+}

package/src/split/ui/SplitRow.tsx

@@ -2,224 +2,33 @@
  * Two figures side by side, with a splitter between them and the share each
  * takes written into the address.
  *
- * How much room the tool deserves beside the figure it feeds is not ours to
- * decide: somebody embedding the chart wants it nearly whole, somebody
- * teaching off the picker wants the picker nearly whole, and both want the
- * link they hand out to open the way they left it. So the splitter is dragged,
- * the share it comes to rest at goes into `?split=`, and the address is the
- * figure.
- *
- * Two things it cannot do, and must not pretend to: on a narrow screen there
- * is no room for two columns at all, so the panes stack and no splitter is
- * drawn; and a link that hid everything one pane holds leaves the other the
- * whole width rather than a share of it.
- *
- * The bar itself is react-science's `SplitPane`, and it keeps react-science's
- * look — barely visible on purpose, found by the pointer that changes over it
- * rather than by the eye. All `chrome.css` says about it is that eleven pixels
- * is more gutter than two figures need.
+ * The body is `splitPanes.tsx`, which `<SplitColumn>` shares; its header is
+ * where the design is written down.
  */
 
-import type { CSSProperties, ReactElement, ReactNode } from 'react';
-import { useRef, useState } from 'react';
-import type { SplitPaneSize } from 'react-science/ui';
-import { SplitPane } from 'react-science/ui';
+import type { ReactElement } from 'react';
 
-import { useResizeObserver } from '../../hooks/ui/useResizeObserver.ts';
-import type { SplitRange } from '../core/split.ts';
-import { clampSplit } from '../core/split.ts';
+import type { SplitPanesProps } from './splitPanes.tsx';
+import { SplitPanes } from './splitPanes.tsx';
 
-/** Props of {@link SplitRow}. */
-export interface SplitRowProps extends SplitRange {
-  /**
-   * Share of the row the first pane takes, as a whole percentage, or `null`
-   * while the page sits at {@link SplitRowProps.defaultRatio}.
-   */
-  ratio: number | null;
-  /** The share the row opens at when the address names none. */
-  defaultRatio: number;
-  /**
-   * Take the share a drag came to rest at, or `null` when the splitter was
-   * double-clicked back to the default.
-   */
-  onRatio: (ratio: number | null) => void;
-  /** The left-hand pane, or `null` when a link left nothing in it. */
-  start: ReactNode;
-  /** The right-hand pane, or `null` when a link left nothing in it. */
-  end: ReactNode;
-  /**
-   * The narrowest row that is still split; under it the two panes stack.
-   * @default 860
-   */
-  stackBelow?: number;
-  /**
-   * The gutter each pane keeps beside the splitter, in pixels, so neither
-   * figure is read against its edge.
-   * @default 6
-   */
-  gutter?: number;
-  /**
-   * The gap between the two panes once they have stacked, in pixels.
-   * @default 16
-   */
-  stackedGap?: number;
-}
+/**
+ * Props of {@link SplitRow}. `start` is the left-hand pane, `end` the
+ * right-hand one, and `stackBelow` a width.
+ */
+export type SplitRowProps = SplitPanesProps;
 
 /**
  * Two panes sharing a row, divided where the address says.
+ *
+ * **Set `max` where the first pane stops being able to use the room.** A pane
+ * of forms dragged past about half the row does not grow: the labels stay put
+ * and the fields stretch to a width nobody types into, so the room becomes
+ * empty card. The figure beside it is what the drag exists to enlarge.
+ *
  * @param props - See {@link SplitRowProps}.
  * @returns The two panes with the splitter between them, the two stacked on a
  * narrow screen, or whichever one a link left on the page, alone.
  */
 export function SplitRow(props: SplitRowProps): ReactElement | null {
-  const {
-    ratio,
-    defaultRatio,
-    onRatio,
-    start,
-    end,
-    min,
-    max,
-    stackBelow = STACK_BELOW,
-    gutter = GUTTER,
-    stackedGap = STACKED_GAP,
-  } = props;
-  const row = useRef<HTMLDivElement>(null);
-  const [width, setWidth] = useState(windowWidth);
-  // The share under the pointer, which is not the one in the address: a drag
-  // reports every pixel it crosses, and the address is rewritten once, where
-  // the splitter is let go.
-  const [dragged, setDragged] = useState<number | null>(null);
-
-  useResizeObserver(row, (size) => {
-    setWidth(size.width);
-  });
-
-  if (start === null && end === null) return null;
-
-  const stacked = start === null || end === null || width < stackBelow;
-  const startPane =
-    start === null ? null : (
-      <div
-        data-testid="split-start"
-        style={stacked ? STACKED_PANE : paneStyle('start', gutter)}
-      >
-        {start}
-      </div>
-    );
-  const endPane =
-    end === null ? null : (
-      <div
-        data-testid="split-end"
-        style={stacked ? STACKED_PANE : paneStyle('end', gutter)}
-      >
-        {end}
-      </div>
-    );
-
-  if (stacked) {
-    return (
-      <div ref={row} style={{ ...STACK, gap: stackedGap }}>
-        {startPane}
-        {endPane}
-      </div>
-    );
-  }
-
-  const share = clampSplit(dragged ?? ratio ?? defaultRatio, { min, max });
-
-  return (
-    // `split-row` is what `chrome.css` reaches the bar through: it is
-    // react-science's own element and carries no class of ours.
-    <div ref={row} className="split-row">
-      <SplitPane
-        direction="horizontal"
-        controlledSide="start"
-        size={`${share}%`}
-        // Held open, so the only layout a visitor can reach is one the address
-        // describes: left to itself a double click collapses a pane, and a link
-        // shared from there would open with the pane back. The double click is
-        // answered here instead, by returning to the page's own share.
-        open
-        onOpenChange={() => {
-          setDragged(null);
-          onRatio(null);
-        }}
-        onSizeChange={(asked) => {
-          setDragged(shareOf(asked, share, { min, max }));
-        }}
-        onResize={(asked) => {
-          const rested = shareOf(asked, share, { min, max });
-          setDragged(null);
-          onRatio(rested);
-        }}
-      >
-        {startPane}
-        {endPane}
-      </SplitPane>
-    </div>
-  );
-}
-
-/**
- * The share a splitter asked for.
- * @param asked - What it reported, a percentage because that is what it was
- * given.
- * @param current - The share in force, kept when the report is not a number.
- * @param range - The range this row is divided in.
- * @returns A whole percentage inside it.
- */
-function shareOf(
-  asked: SplitPaneSize,
-  current: number,
-  range: SplitRange,
-): number {
-  const value = Number.parseFloat(asked);
-  return Number.isFinite(value) ? clampSplit(value, range) : current;
-}
-
-/**
- * How wide the window is, which is what the row is taken to be until it has
- * been measured. Reading it rather than starting at zero is what keeps a wide
- * page from laying itself out stacked and splitting a frame later, which would
- * build both figures twice on every load.
- * @returns The width in pixels, or the threshold itself where there is no
- * window to read — a test, or a page rendered to a string — which is the
- * narrowest a row is still split at.
- */
-function windowWidth(): number {
-  const { innerWidth } = globalThis;
-  return typeof innerWidth === 'number' && innerWidth > 0
-    ? innerWidth
-    : STACK_BELOW;
-}
-
-/** The narrowest row that is still split, in pixels. */
-const STACK_BELOW = 860;
-
-/** The gutter a pane keeps beside the splitter, in pixels. */
-const GUTTER = 6;
-
-/** The gap between the panes once they have stacked, in pixels. */
-const STACKED_GAP = 16;
-
-const STACK = {
-  display: 'flex',
-  flexDirection: 'column',
-} as const satisfies CSSProperties;
-
-const STACKED_PANE = {
-  display: 'flex',
-  flexDirection: 'column',
-  minWidth: 0,
-} as const satisfies CSSProperties;
-
-function paneStyle(side: 'start' | 'end', gutter: number): CSSProperties {
-  return {
-    display: 'flex',
-    flex: '1 1 0%',
-    flexDirection: 'column',
-    minWidth: 0,
-    [side === 'start' ? 'paddingRight' : 'paddingLeft']: gutter,
-  };
+  return <SplitPanes direction="horizontal" {...props} />;
 }

package/src/split/ui/index.ts

@@ -1,2 +1,5 @@
+export type { SplitColumnProps } from './SplitColumn.tsx';
+export { SplitColumn } from './SplitColumn.tsx';
 export type { SplitRowProps } from './SplitRow.tsx';
 export { SplitRow } from './SplitRow.tsx';
+export type { SplitPanesProps } from './splitPanes.tsx';

package/src/split/ui/splitPanes.tsx

@@ -0,0 +1,267 @@
+/**
+ * Two figures with a splitter between them, and the share each takes written
+ * into the address. The body of `<SplitRow>` and `<SplitColumn>` both.
+ *
+ * How much room one half deserves beside the other is not ours to decide:
+ * somebody embedding the chart wants it nearly whole, somebody teaching off the
+ * picker wants the picker nearly whole, and both want the link they hand out to
+ * open the way they left it. So the splitter is dragged, the share it comes to
+ * rest at goes into `?split=`, and the address is the figure.
+ *
+ * Two things it cannot do, and must not pretend to: on a screen with no room
+ * for two the panes stack and no splitter is drawn; and a link that hid
+ * everything one pane holds leaves the other the whole of it rather than a
+ * share.
+ *
+ * The bar itself is react-science's `SplitPane`, and it keeps react-science's
+ * look — barely visible on purpose, found by the pointer that changes over it
+ * rather than by the eye. All `chrome.css` says about it is that eleven pixels
+ * is more gutter than two figures need.
+ */
+
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import { useRef, useState } from 'react';
+import type { SplitPaneSize } from 'react-science/ui';
+import { SplitPane } from 'react-science/ui';
+
+import { useResizeObserver } from '../../hooks/ui/useResizeObserver.ts';
+import type { SplitRange } from '../core/split.ts';
+import { clampSplit } from '../core/split.ts';
+
+/** What both splitters take. */
+export interface SplitPanesProps extends SplitRange {
+  /**
+   * Share of the box the first pane takes, as a whole percentage, or `null`
+   * while the page sits at {@link SplitPanesProps.defaultRatio}.
+   */
+  ratio: number | null;
+  /** The share it opens at when the address names none. */
+  defaultRatio: number;
+  /**
+   * Take the share a drag came to rest at, or `null` when the splitter was
+   * double-clicked back to the default.
+   */
+  onRatio: (ratio: number | null) => void;
+  /** The first pane — left, or top — or `null` when a link left nothing in it. */
+  start: ReactNode;
+  /** The second pane, or `null` when a link left nothing in it. */
+  end: ReactNode;
+  /**
+   * The smallest box that is still split, in pixels — a width for a row, a
+   * height for a column. Under it the two panes stack and no splitter is drawn.
+   * @default 860 across, 420 down
+   */
+  stackBelow?: number;
+  /**
+   * The gutter each pane keeps beside the splitter, in pixels, so neither
+   * figure is read against its edge.
+   * @default 6
+   */
+  gutter?: number;
+  /**
+   * The gap between the two panes once they have stacked, in pixels.
+   * @default 16
+   */
+  stackedGap?: number;
+}
+
+/** What {@link SplitPanes} takes on top of the public props. */
+interface InternalProps extends SplitPanesProps {
+  /** Across the box, or down it. */
+  direction: 'horizontal' | 'vertical';
+}
+
+/**
+ * The two panes, divided where the address says.
+ *
+ * @param props - See {@link SplitPanesProps}.
+ * @returns The panes with the splitter between them, the two stacked where
+ * there is no room for both, or whichever one a link left, alone.
+ */
+export function SplitPanes(props: InternalProps): ReactElement | null {
+  const {
+    direction,
+    ratio,
+    defaultRatio,
+    onRatio,
+    start,
+    end,
+    min,
+    max,
+    stackBelow = direction === 'horizontal' ? STACK_ACROSS : STACK_DOWN,
+    gutter = GUTTER,
+    stackedGap = STACKED_GAP,
+  } = props;
+  const across = direction === 'horizontal';
+  const box = useRef<HTMLDivElement>(null);
+  const [size, setSize] = useState(() => viewportSize(across, stackBelow));
+  // The share under the pointer, which is not the one in the address: a drag
+  // reports every pixel it crosses, and the address is rewritten once, where
+  // the splitter is let go.
+  const [dragged, setDragged] = useState<number | null>(null);
+
+  useResizeObserver(box, (measured) => {
+    setSize(across ? measured.width : measured.height);
+  });
+
+  if (start === null && end === null) return null;
+
+  // A column divided by a share needs a box of a definite height to take a
+  // share of; in an ordinary page-height one it would measure zero and both
+  // panes would collapse, so it stacks instead and says nothing about it.
+  const stacked = start === null || end === null || size < stackBelow;
+  const startPane =
+    start === null ? null : (
+      <div
+        data-testid="split-start"
+        style={stacked ? STACKED_PANE : paneStyle(across, 'start', gutter)}
+      >
+        {start}
+      </div>
+    );
+  const endPane =
+    end === null ? null : (
+      <div
+        data-testid="split-end"
+        style={stacked ? STACKED_PANE : paneStyle(across, 'end', gutter)}
+      >
+        {end}
+      </div>
+    );
+
+  if (stacked) {
+    return (
+      <div ref={box} style={{ ...STACK, gap: stackedGap }}>
+        {startPane}
+        {endPane}
+      </div>
+    );
+  }
+
+  const share = clampSplit(dragged ?? ratio ?? defaultRatio, { min, max });
+
+  return (
+    // `split-row` is what `chrome.css` reaches the bar through: it is
+    // react-science's own element and carries no class of ours.
+    <div ref={box} className="split-row" style={across ? undefined : FILL}>
+      <SplitPane
+        direction={direction}
+        controlledSide="start"
+        size={`${share}%`}
+        // Held open, so the only layout a visitor can reach is one the address
+        // describes: left to itself a double click collapses a pane, and a link
+        // shared from there would open with the pane back. The double click is
+        // answered here instead, by returning to the page's own share.
+        open
+        onOpenChange={() => {
+          setDragged(null);
+          onRatio(null);
+        }}
+        onSizeChange={(asked) => {
+          setDragged(shareOf(asked, share, { min, max }));
+        }}
+        onResize={(asked) => {
+          const rested = shareOf(asked, share, { min, max });
+          setDragged(null);
+          onRatio(rested);
+        }}
+      >
+        {startPane}
+        {endPane}
+      </SplitPane>
+    </div>
+  );
+}
+
+/**
+ * The share a splitter asked for.
+ *
+ * @param asked - What it reported, a percentage because that is what it was
+ * given.
+ * @param current - The share in force, kept when the report is not a number.
+ * @param range - The range this box is divided in.
+ * @returns A whole percentage inside it.
+ */
+function shareOf(
+  asked: SplitPaneSize,
+  current: number,
+  range: SplitRange,
+): number {
+  const value = Number.parseFloat(asked);
+  return Number.isFinite(value) ? clampSplit(value, range) : current;
+}
+
+/**
+ * How big the window is, which is what the box is taken to be until it has been
+ * measured. Reading it rather than starting at zero is what keeps a wide page
+ * from laying itself out stacked and splitting a frame later, which would build
+ * both figures twice on every load.
+ *
+ * @param across - Whether the box is divided across or down.
+ * @param fallback - What to answer where there is no window to read — a test,
+ * or a page rendered to a string.
+ * @returns The size in pixels.
+ */
+function viewportSize(across: boolean, fallback: number): number {
+  const measure = across ? globalThis.innerWidth : globalThis.innerHeight;
+  return typeof measure === 'number' && measure > 0 ? measure : fallback;
+}
+
+/** The narrowest box still divided across, in pixels. */
+const STACK_ACROSS = 860;
+
+/**
+ * The shortest box still divided down, in pixels. Two figures sharing less than
+ * this have about two hundred pixels each, which is under what any of them
+ * reads at.
+ */
+const STACK_DOWN = 420;
+
+/** The gutter a pane keeps beside the splitter, in pixels. */
+const GUTTER = 6;
+
+/** The gap between the panes once they have stacked, in pixels. */
+const STACKED_GAP = 16;
+
+const STACK = {
+  display: 'flex',
+  flexDirection: 'column',
+  minHeight: 0,
+} as const satisfies CSSProperties;
+
+const STACKED_PANE = {
+  display: 'flex',
+  flexDirection: 'column',
+  minWidth: 0,
+  minHeight: 0,
+} as const satisfies CSSProperties;
+
+/** A column takes the height it is given, so its share has something to divide. */
+const FILL = {
+  display: 'flex',
+  flex: '1 1 0%',
+  flexDirection: 'column',
+  minHeight: 0,
+} as const satisfies CSSProperties;
+
+function paneStyle(
+  across: boolean,
+  side: 'start' | 'end',
+  gutter: number,
+): CSSProperties {
+  const edge = across
+    ? side === 'start'
+      ? 'paddingRight'
+      : 'paddingLeft'
+    : side === 'start'
+      ? 'paddingBottom'
+      : 'paddingTop';
+  return {
+    display: 'flex',
+    flex: '1 1 0%',
+    flexDirection: 'column',
+    minWidth: 0,
+    minHeight: 0,
+    [edge]: gutter,
+  };
+}