react-cheminfo 0.31.0 → 0.32.0

package/src/number/core/numberText.ts

@@ -0,0 +1,91 @@
+/**
+ * The number a box of text reads as, and the text a number is shown with.
+ *
+ * A box that hands its text straight to `Number` is a box nobody can type a
+ * decimal into: `0.` reads as `0`, and a control rendered from that number
+ * writes `0` back over the dot before the next keystroke arrives. So the text
+ * and the number are two values here, and the text is the one the reader owns.
+ */
+
+/** Text that reads as a finite number, comma or dot. */
+const NUMBER = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i;
+
+/** Text a reader is partway through: `-`, `0.`, `1e`, `1e-`, or empty. */
+const PARTIAL = /^[+-]?(?:\d+(?:\.\d*)?|\.\d*)(?:e[+-]?\d*)?$/i;
+
+/** A sign on its own, which is where typing a negative number starts. */
+const SIGN = /^[+-]?$/;
+
+/** Decimals `roundTo` can keep, and the most a step is rounded to. */
+const MAXIMUM_DECIMALS = 15;
+
+/**
+ * The number some text reads as.
+ *
+ * A decimal comma is read as a decimal point, because a keyboard laid out for
+ * French or German puts a comma where the number pad's decimal key is and a
+ * reader typing `0,2` means two tenths.
+ * @param text - What is in the box.
+ * @param integer - Whether only whole numbers are wanted. Defaults to `false`.
+ * @returns The number, or undefined while the text does not read as one.
+ */
+export function readNumber(text: string, integer = false): number | undefined {
+  const trimmed = text.trim().replace(',', '.');
+  if (!NUMBER.test(trimmed)) return undefined;
+  const parsed = Number(trimmed);
+  if (!Number.isFinite(parsed)) return undefined;
+  if (integer && !Number.isInteger(parsed)) return undefined;
+  return parsed;
+}
+
+/**
+ * Whether the text can still become a number as more is typed.
+ *
+ * `0.`, `-` and `1e-` are all on the way to a number and must not be reported
+ * as mistakes; `0.2x` is not, and a box may say so while it is being typed.
+ * @param text - What is in the box.
+ * @returns Whether anything typed so far rules a number out.
+ */
+export function isPartialNumber(text: string): boolean {
+  const trimmed = text.trim().replace(',', '.');
+  return SIGN.test(trimmed) || PARTIAL.test(trimmed);
+}
+
+/**
+ * The text a number is shown with.
+ * @param value - The number, or nothing when the box is empty.
+ * @returns Its text, empty when there is no number.
+ */
+export function numberText(value: number | undefined): string {
+  return value === undefined || !Number.isFinite(value) ? '' : String(value);
+}
+
+/**
+ * A number moved by one press of an arrow key or a stepper button.
+ *
+ * The result is rounded to the decimals the two operands carry, so stepping
+ * `0.1` up by `0.2` lands on `0.3` rather than on `0.30000000000000004` — a
+ * value that is then shown, shared in a link and stored in full.
+ * @param value - Where the box is now.
+ * @param delta - What the press adds; negative going down.
+ * @returns The number the box moves to.
+ */
+export function stepNumber(value: number, delta: number): number {
+  const decimals = Math.max(decimalsOf(value), decimalsOf(delta));
+  const moved = value + delta;
+  if (decimals === 0) return moved;
+  const factor = 10 ** decimals;
+  return Math.round(moved * factor) / factor;
+}
+
+/**
+ * How many decimals a number is written with.
+ * @param value - The number.
+ * @returns Its count of decimals, `0` for anything written in exponent form.
+ */
+function decimalsOf(value: number): number {
+  const text = String(Math.abs(value));
+  const dot = text.indexOf('.');
+  if (dot === -1 || text.includes('e')) return 0;
+  return Math.min(text.length - dot - 1, MAXIMUM_DECIMALS);
+}

package/src/number/ui/NumberInput.tsx

@@ -0,0 +1,300 @@
+import {
+  Button,
+  ButtonGroup,
+  Classes,
+  ControlGroup,
+  InputGroup,
+} from '@blueprintjs/core';
+import type { CSSProperties, KeyboardEvent, ReactElement } from 'react';
+import { useState } from 'react';
+
+import { clamp } from '../../format/core/clamp.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import {
+  isPartialNumber,
+  numberText,
+  readNumber,
+  stepNumber,
+} from '../core/numberText.ts';
+
+/** What every number box takes, whether or not it can be left empty. */
+export interface NumberInputBaseProps {
+  /**
+   * Smallest accepted value, applied when the box is left rather than while it
+   * is typed in.
+   * @default undefined — unbounded below
+   */
+  min?: number;
+  /**
+   * Largest accepted value, applied when the box is left.
+   * @default undefined — unbounded above
+   */
+  max?: number;
+  /**
+   * What one press of an arrow key or a stepper button adds; Shift multiplies
+   * it by ten and Alt divides it by ten.
+   * @default 1
+   */
+  step?: number;
+  /**
+   * Whether only whole numbers are wanted. A typed decimal is rounded when the
+   * box is left.
+   * @default false
+   */
+  integer?: boolean;
+  /**
+   * Whether the up and down buttons are drawn beside the box.
+   * @default true
+   */
+  buttons?: boolean;
+  /**
+   * Grey text shown while the box is empty.
+   * @default undefined — the box carries no placeholder
+   */
+  placeholder?: string;
+  /** @default false */
+  disabled?: boolean;
+  /**
+   * Whether the control takes the whole width it is given.
+   * @default false
+   */
+  fill?: boolean;
+  /** @default 'medium' */
+  size?: 'small' | 'medium' | 'large';
+  /**
+   * Accessible name, for a box no `<label>` points at.
+   * @default undefined — the box is named by its label
+   */
+  ariaLabel?: string;
+  /**
+   * The box's id, for a `<label htmlFor>` elsewhere in the form.
+   * @default undefined
+   */
+  id?: string;
+  /**
+   * A name a test finds the box by, written as `data-testid`.
+   * @default undefined
+   */
+  testId?: string;
+  /**
+   * Drawn inside the box at its left — a unit, a prefix such as `10⁻`.
+   * @default undefined
+   */
+  leftElement?: ReactElement;
+  /**
+   * Drawn inside the box at its right — a unit, a small button.
+   * @default undefined
+   */
+  rightElement?: ReactElement;
+  /** @default undefined */
+  className?: string;
+  /** @default undefined */
+  style?: CSSProperties;
+}
+
+/** A box that always holds a number. */
+export interface RequiredNumberInputProps extends NumberInputBaseProps {
+  /** The number the box shows. */
+  value: number;
+  /**
+   * Whether an emptied box hands up nothing. A required box keeps the number
+   * it had and shows it again when the box is left.
+   * @default false
+   */
+  allowEmpty?: false;
+  /** Called with the new number, never while the text is half-typed. */
+  onChange: (value: number) => void;
+}
+
+/** A box that may be left empty, which hands up `undefined`. */
+export interface OptionalNumberInputProps extends NumberInputBaseProps {
+  /** The number the box shows, or nothing when it is empty. */
+  value: number | undefined;
+  allowEmpty: true;
+  /** Called with the new number, or with `undefined` when the box is emptied. */
+  onChange: (value: number | undefined) => void;
+}
+
+/** See {@link NumberInput}. */
+export type NumberInputProps =
+  RequiredNumberInputProps | OptionalNumberInputProps;
+
+/**
+ * A number typed into a box.
+ *
+ * The box keeps what was typed rather than what parsed. A reader halfway
+ * through `0.2` has typed `0.`, which reads as zero, and a box rendered from
+ * that number would write `0` back over the dot before the `2` arrives —
+ * which is why Blueprint's `NumericInput` cannot be given a number to show and
+ * is never used directly on our sites. Nothing is handed up until the text
+ * reads as a number, so a calculation never sees a half-typed value, and the
+ * bounds are applied when the box is left rather than under the caret.
+ * @param props - See {@link NumberInputProps}.
+ * @returns The box, with its stepper buttons unless they are turned off.
+ */
+export function NumberInput(props: NumberInputProps): ReactElement {
+  const {
+    value,
+    min,
+    max,
+    step = 1,
+    integer = false,
+    allowEmpty = false,
+    buttons = true,
+    placeholder,
+    disabled = false,
+    fill = false,
+    size = 'medium',
+    ariaLabel,
+    id,
+    testId,
+    leftElement,
+    rightElement,
+    className,
+    style,
+  } = props;
+  const t = useChromeT();
+  const onChange = props.onChange as (next: number | undefined) => void;
+  const [draft, setDraft] = useState(() => ({
+    text: numberText(value),
+    held: value,
+  }));
+
+  // The number changed elsewhere — a preset, a reset, a link — so the box has
+  // to follow. `held` is what this box last handed up, not the prop it was
+  // rendered with: comparing against the prop would make the box's own edit
+  // look external and rewrite `-0.` as `0` under the caret.
+  if (draft.held !== value) setDraft({ text: numberText(value), held: value });
+
+  function hold(text: string, held: number | undefined) {
+    setDraft({ text, held });
+  }
+
+  function commit(next: number) {
+    hold(numberText(next), next);
+    onChange(next);
+  }
+
+  function type(text: string) {
+    const emptied = text.trim() === '';
+    const parsed = readNumber(text, integer);
+    hold(text, emptied && allowEmpty ? undefined : (parsed ?? value));
+    if (emptied) {
+      if (allowEmpty) onChange(undefined);
+    } else if (parsed !== undefined) {
+      onChange(parsed);
+    }
+  }
+
+  function leave() {
+    if (draft.text.trim() === '') {
+      if (!allowEmpty) hold(numberText(value), value);
+      return;
+    }
+    const parsed = readNumber(draft.text);
+    if (parsed === undefined) {
+      hold(numberText(value), value);
+      return;
+    }
+    const settled = settle(parsed, integer, min, max);
+    if (settled !== parsed || !Object.is(settled, value)) commit(settled);
+  }
+
+  function press(event: KeyboardEvent<HTMLInputElement>) {
+    const direction =
+      event.key === 'ArrowUp' ? 1 : event.key === 'ArrowDown' ? -1 : 0;
+    if (direction === 0 || disabled) return;
+    event.preventDefault();
+    const scale = event.shiftKey ? 10 : event.altKey ? 0.1 : 1;
+    move(direction * scale);
+  }
+
+  function move(scale: number) {
+    const from = readNumber(draft.text) ?? value ?? 0;
+    commit(settle(stepNumber(from, step * scale), integer, min, max));
+  }
+
+  const box = (
+    <InputGroup
+      id={id}
+      size={size}
+      fill={fill}
+      disabled={disabled}
+      placeholder={placeholder}
+      value={draft.text}
+      intent={isPartialNumber(draft.text) ? 'none' : 'danger'}
+      inputMode={integer ? 'numeric' : 'decimal'}
+      spellCheck={false}
+      autoComplete="off"
+      autoCorrect="off"
+      autoCapitalize="off"
+      aria-label={ariaLabel}
+      data-testid={testId}
+      leftElement={leftElement}
+      rightElement={rightElement}
+      className={buttons ? undefined : className}
+      style={buttons ? undefined : style}
+      onValueChange={type}
+      onKeyDown={press}
+      onBlur={leave}
+    />
+  );
+
+  if (!buttons) return box;
+
+  const shown = readNumber(draft.text) ?? value;
+  return (
+    <ControlGroup
+      fill={fill}
+      style={style}
+      className={[Classes.NUMERIC_INPUT, className].filter(Boolean).join(' ')}
+    >
+      {box}
+      <ButtonGroup className={Classes.FIXED} vertical>
+        <Button
+          icon="chevron-up"
+          size={size}
+          aria-label={t('number.increment')}
+          disabled={
+            disabled ||
+            (max !== undefined && shown !== undefined && shown >= max)
+          }
+          onClick={() => move(1)}
+        />
+        <Button
+          icon="chevron-down"
+          size={size}
+          aria-label={t('number.decrement')}
+          disabled={
+            disabled ||
+            (min !== undefined && shown !== undefined && shown <= min)
+          }
+          onClick={() => move(-1)}
+        />
+      </ButtonGroup>
+    </ControlGroup>
+  );
+}
+
+/**
+ * The number a box settles on once it is left or stepped.
+ * @param value - What the text read as.
+ * @param integer - Whether only whole numbers are wanted.
+ * @param min - Smallest accepted value, when there is one.
+ * @param max - Largest accepted value, when there is one.
+ * @returns The rounded, bounded number.
+ */
+function settle(
+  value: number,
+  integer: boolean,
+  min: number | undefined,
+  max: number | undefined,
+): number {
+  const rounded = integer ? Math.round(value) : value;
+  return clamp(
+    rounded,
+    min ?? Number.NEGATIVE_INFINITY,
+    max ?? Number.POSITIVE_INFINITY,
+    rounded,
+  );
+}

package/src/number/ui/index.ts

@@ -0,0 +1,7 @@
+export type {
+  NumberInputBaseProps,
+  NumberInputProps,
+  OptionalNumberInputProps,
+  RequiredNumberInputProps,
+} from './NumberInput.tsx';
+export { NumberInput } from './NumberInput.tsx';

package/src/periodic/ui/ElementCell.tsx

@@ -4,9 +4,14 @@
  *
  * A cell is a real `<button>`, so Tab reaches it, Enter and Space activate it,
  * and a screen reader reads the element's name rather than its symbol.
+ *
+ * Everything written in it is sized in container-query units, so a cell shows
+ * the same proportions at 280px beside a chart and across a lecture-hall
+ * screen — the table a class reads is the same drawing, larger.
  */
 
 import type { CSSProperties, ReactElement } from 'react';
+import { useState } from 'react';
 
 import type { Swatch } from '../../color/core/interpolate.ts';
 import { useChromeT } from '../../i18n/ui/useT.ts';
@@ -32,6 +37,12 @@ export interface ElementCellProps {
    * @default '' — nothing is written
    */
   detail?: string;
+  /**
+   * Whether the table this cell belongs to writes a third line at all. A table
+   * that writes none gives the room to the symbol, and its rows are shorter.
+   * @default whether this cell has one
+   */
+  writesDetail?: boolean;
   /**
    * Whether the cell is the one the tools are pointed at.
    * @default false
@@ -71,11 +82,13 @@ export function ElementCell(props: ElementCellProps): ReactElement {
     row,
     onSelect,
     detail = '',
+    writesDetail = detail !== '',
     isSelected = false,
     isIncluded = true,
     onHover,
   } = props;
   const t = useChromeT();
+  const [isHovered, setIsHovered] = useState(false);
 
   return (
     <button
@@ -83,6 +96,7 @@ export function ElementCell(props: ElementCellProps): ReactElement {
       className={className}
       data-testid={`element-${symbol}`}
       data-symbol={symbol}
+      title={detail === '' ? name : `${name} · ${detail}`}
       aria-label={t('periodic.cellLabel', {
         name,
         symbol,
@@ -92,8 +106,14 @@ export function ElementCell(props: ElementCellProps): ReactElement {
       onClick={() => {
         onSelect(symbol);
       }}
-      onPointerEnter={() => onHover?.(symbol)}
-      onPointerLeave={() => onHover?.(null)}
+      onPointerEnter={() => {
+        setIsHovered(true);
+        onHover?.(symbol);
+      }}
+      onPointerLeave={() => {
+        setIsHovered(false);
+        onHover?.(null);
+      }}
       style={{
         ...cellStyle,
         gridColumn: column,
@@ -103,17 +123,134 @@ export function ElementCell(props: ElementCellProps): ReactElement {
         opacity: isIncluded ? 1 : 0.28,
         // An outline rather than a fill: a table coloured by a property must
         // keep saying what the value is while a cell is selected.
-        outline: isSelected ? `2px solid ${swatch.foreground}` : 'none',
-        outlineOffset: -3,
+        outlineStyle: isSelected ? 'solid' : 'none',
+        outlineColor: swatch.foreground,
+        // Thick enough to be seen from the back of a room, and drawn inside
+        // the cell so a neighbour never covers it.
+        outlineWidth: 'max(2px, 0.3cqw)',
+        outlineOffset: 'max(-3px, -0.4cqw)',
+        // The cell the pointer is on, for a class following a demonstration.
+        filter: isHovered ? 'brightness(1.08)' : undefined,
       }}
     >
       <span style={numberStyle}>{atomicNumber}</span>
-      <span style={symbolStyle}>{symbol}</span>
-      {detail === '' ? null : <span style={detailStyle}>{detail}</span>}
+      <span
+        style={{
+          ...symbolStyle,
+          fontSize: symbolFontSize(symbol, writesDetail),
+        }}
+      >
+        {symbol}
+      </span>
+      {detail === '' ? null : (
+        <span style={{ ...detailStyle, fontSize: detailFontSize(detail) }}>
+          {detail}
+        </span>
+      )}
     </button>
   );
 }
 
+/**
+ * The size the symbol is written at.
+ *
+ * Every symbol is written at the same size, except the widest of them — the
+ * ones whose second letter is an `m` — which are written a tenth smaller
+ * rather than run into the edges of their cell.
+ * @param symbol - The chemical symbol.
+ * @param writesDetail - Whether the table writes a third line under it.
+ * @returns A CSS length.
+ */
+function symbolFontSize(symbol: string, writesDetail: boolean): string {
+  const cap = writesDetail ? SYMBOL_CQW : SYMBOL_ALONE_CQW;
+  return fitted(symbolWidthInEm(symbol), cap, '0.5rem');
+}
+
+/**
+ * The size the third line takes so the whole of it is written.
+ *
+ * A value cut short by an ellipsis is a wrong value — `0.0899` read as `0.0…`
+ * is worse than not writing it at all — so a long string is written smaller
+ * rather than trimmed.
+ * @param detail - What the third line says.
+ * @returns A CSS length.
+ */
+function detailFontSize(detail: string): string {
+  return fitted(detailWidthInEm(detail), DETAIL_CQW, '0.25rem');
+}
+
+/**
+ * The largest size a string of the given width fits its cell at.
+ *
+ * The room a cell leaves is a share of the table's width less its border and
+ * its padding, which are the same few pixels at every size — hence the two
+ * units in one expression.
+ * @param widthInEm - How wide the string is, in ems of its own size.
+ * @param cap - The size it is written at when it has room to spare.
+ * @param floor - The size under which it is not shrunk any further.
+ * @returns A CSS length.
+ */
+function fitted(widthInEm: number, cap: string, floor: string): string {
+  const room = `calc((${CELL_CQW} - ${CELL_CHROME}) / ${widthInEm.toFixed(2)})`;
+  return `max(${floor}, min(${cap}, ${room}))`;
+}
+
+/**
+ * How wide a symbol is, in ems of its own size.
+ * @param symbol - The chemical symbol.
+ * @returns Its width, never zero.
+ */
+function symbolWidthInEm(symbol: string): number {
+  let width = 0;
+  for (const character of symbol) {
+    if (character === 'm' || character === 'w') {
+      width += 0.95;
+    } else if (character >= 'a' && character <= 'z') {
+      width += 0.63;
+    } else {
+      width += 0.85;
+    }
+  }
+  return Math.max(width, 0.85);
+}
+
+/**
+ * How wide the third line is, in ems of its own size.
+ *
+ * It is written with tabular figures, where every glyph — the decimal point
+ * and the minus of an exponent included — advances the same width, so counting
+ * the characters is the measurement.
+ * @param detail - What the third line says.
+ * @returns Its width, never zero.
+ */
+function detailWidthInEm(detail: string): number {
+  return Math.max(detail.length, 1) * TABULAR_EM;
+}
+
+/** What one tabular glyph advances, as a share of its own size. */
+const TABULAR_EM = 0.6;
+
+/** The size the symbol is written at wherever it fits, as a share of the table. */
+const SYMBOL_CQW = '2.4cqw';
+
+/** The same, in a table that writes nothing under the symbol. */
+const SYMBOL_ALONE_CQW = '2.8cqw';
+
+/**
+ * The tallest the third line is ever written, as a share of the table.
+ *
+ * Close to three quarters of the symbol: the symbol is how a cell is found,
+ * but the value is what the table is being read for, and a value half the size
+ * of the symbol is the one thing on the cell a class cannot make out.
+ */
+const DETAIL_CQW = '1.75cqw';
+
+/** How wide one column is, as a share of the table's width. */
+const CELL_CQW = '4.85cqw';
+
+/** What the border and the padding of a cell take off that width. */
+const CELL_CHROME = '4px';
+
 const cellStyle = {
   alignItems: 'center',
   border: '1px solid rgb(255 255 255 / 0.55)',
@@ -123,29 +260,31 @@ const cellStyle = {
   flexDirection: 'column',
   font: 'inherit',
   justifyContent: 'center',
-  lineHeight: 1.05,
   minWidth: 0,
   overflow: 'hidden',
-  padding: 1,
-  transition: 'opacity 120ms ease',
+  padding: '1px',
+  transition: 'opacity 120ms ease, filter 120ms ease',
 } as const satisfies CSSProperties;
 
 const numberStyle = {
   alignSelf: 'flex-start',
-  fontSize: 'clamp(0.34rem, 1.6cqw, 0.5rem)',
+  fontSize: 'max(0.33rem, 1.2cqw)',
+  fontVariantNumeric: 'tabular-nums',
+  lineHeight: 1,
   opacity: 0.8,
-  paddingLeft: 2,
+  paddingLeft: '0.15cqw',
 } as const satisfies CSSProperties;
 
 const symbolStyle = {
-  fontSize: 'clamp(0.55rem, 3.3cqw, 1.05rem)',
   fontWeight: 700,
+  letterSpacing: '-0.02em',
+  lineHeight: 1.02,
 } as const satisfies CSSProperties;
 
 const detailStyle = {
-  fontSize: 'clamp(0.34rem, 1.6cqw, 0.5rem)',
+  fontVariantNumeric: 'tabular-nums',
+  lineHeight: 1,
   maxWidth: '100%',
   overflow: 'hidden',
-  textOverflow: 'ellipsis',
   whiteSpace: 'nowrap',
 } as const satisfies CSSProperties;