react-cheminfo 0.31.0 → 0.33.0

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/orbital/ui/AtomicOrbitalCanvas.tsx

@@ -64,11 +64,21 @@ interface AtomicOrbitalCanvasProps {
    */
   onAxesChange?: (axes: boolean) => void;
   /**
-   * Whether the scene turns on its own, which is what makes a still screenshot
-   * of a 3D shape readable.
+   * Whether the scene turns on its own when the canvas opens, which is what
+   * makes a still screenshot of a 3D shape readable.
+   *
+   * The canvas owns the state from then on: the button in its corner flips it,
+   * and {@link AtomicOrbitalCanvasProps.onSpinningChange} reports the new value
+   * to a site that wants to remember it for the next mount.
    * @default false
    */
   spinning?: boolean;
+  /**
+   * Called when the student flips the spin, with its new state — so a site can
+   * persist the choice and pass it back as `spinning`.
+   * @default undefined
+   */
+  onSpinningChange?: (spinning: boolean) => void;
   /**
    * How fast it turns, in molstar's own spin unit. Lower is slower.
    * @default 0.3
@@ -108,10 +118,11 @@ export function AtomicOrbitalCanvas(
     palette = PHASE_PALETTES.textbook,
     resolution = DEFAULT_RESOLUTION,
     axes: initialAxes = true,
-    spinning = false,
+    spinning: initialSpinning = false,
     spinSpeed = DEFAULT_SPIN_SPEED,
     sample = sampleInProcess,
     onAxesChange,
+    onSpinningChange,
     onNodeRadii,
     onFailureChange,
   } = props;
@@ -129,6 +140,7 @@ export function AtomicOrbitalCanvas(
   const axesRef = useRef(initialAxes);
 
   const [axes, setAxes] = useState(initialAxes);
+  const [spinning, setSpinning] = useState(initialSpinning);
 
   // What the canvas is being asked to show. Comparing it with what it *is*
   // showing gives the progress note without a state write on every prop change.
@@ -137,9 +149,19 @@ export function AtomicOrbitalCanvas(
 
   // Callbacks are read through refs so a caller passing an inline arrow does
   // not re-sample the orbital on every render of its parent.
-  const callbacks = useRef({ onAxesChange, onNodeRadii, onFailureChange });
+  const callbacks = useRef({
+    onAxesChange,
+    onSpinningChange,
+    onNodeRadii,
+    onFailureChange,
+  });
   useEffect(() => {
-    callbacks.current = { onAxesChange, onNodeRadii, onFailureChange };
+    callbacks.current = {
+      onAxesChange,
+      onSpinningChange,
+      onNodeRadii,
+      onFailureChange,
+    };
   });
 
   // Created and disposed once per mount. React 19 runs this twice in
@@ -210,6 +232,11 @@ export function AtomicOrbitalCanvas(
           setAxes(!axes);
           callbacks.current.onAxesChange?.(!axes);
         }}
+        spinning={spinning}
+        onToggleSpin={() => {
+          setSpinning(!spinning);
+          callbacks.current.onSpinningChange?.(!spinning);
+        }}
         onResetView={() => {
           void viewerRef.current?.resetView();
         }}

package/src/orbital/ui/AtomicOrbitalControls.tsx

@@ -1,7 +1,8 @@
 /**
- * The two controls an orbital canvas owns: the cartesian frame, and the way
- * back to the framing the orbital opened on — a change of orbital keeps
- * whatever angle and zoom the student is on.
+ * The three controls an orbital canvas owns: the cartesian frame, the slow
+ * spin that makes a 3D shape readable on a flat screen, and the way back to the
+ * framing the orbital opened on — a change of orbital keeps whatever angle and
+ * zoom the student is on.
  */
 
 import { Button } from '@blueprintjs/core';
@@ -17,25 +18,33 @@ interface AtomicOrbitalControlsProps {
   axes: boolean;
   /** Called when the frame button is pressed. */
   onToggleAxes: () => void;
+  /** Whether the scene is turning. */
+  spinning: boolean;
+  /** Called when the spin button is pressed. */
+  onToggleSpin: () => void;
   /** Called when the reset button is pressed. */
   onResetView: () => void;
 }
 
 /**
- * The frame and reset buttons, in the canvas's top-right corner.
+ * The frame, spin and reset buttons, in the canvas's top-right corner.
  * @param props - See {@link AtomicOrbitalControlsProps}.
- * @returns The two buttons.
+ * @returns The three buttons.
  */
 export function AtomicOrbitalControls(
   props: AtomicOrbitalControlsProps,
 ): ReactElement {
-  const { axes, onToggleAxes, onResetView } = props;
+  const { axes, onToggleAxes, spinning, onToggleSpin, onResetView } = props;
   const t = useChromeT();
   const axesHelp: HelpContent = {
     title: t('orbital.axesTitle'),
     body: t('orbital.axesBody'),
     example: { code: '3d_yz', note: t('orbital.axesExample') },
   };
+  const spinHelp: HelpContent = {
+    title: t('orbital.spinTitle'),
+    body: t('orbital.spinBody'),
+  };
   const resetHelp: HelpContent = {
     title: t('orbital.resetTitle'),
     body: t('orbital.resetBody'),
@@ -53,6 +62,17 @@ export function AtomicOrbitalControls(
           onClick={onToggleAxes}
         />
       </HelpTooltip>
+      <HelpTooltip content={spinHelp} placement="bottom">
+        <Button
+          variant="minimal"
+          size="small"
+          icon="refresh"
+          active={spinning}
+          aria-label={t('orbital.spin')}
+          aria-pressed={spinning}
+          onClick={onToggleSpin}
+        />
+      </HelpTooltip>
       <HelpTooltip content={resetHelp} placement="bottom">
         <Button
           variant="minimal"

package/src/orbital/ui/AtomicOrbitalViewer.tsx

@@ -68,10 +68,17 @@ export interface AtomicOrbitalViewerProps {
    */
   onAxesChange?: (axes: boolean) => void;
   /**
-   * Whether the scene turns on its own.
+   * Whether the scene turns on its own when the canvas opens. The button in the
+   * canvas's corner flips it from there.
    * @default false
    */
   spinning?: boolean;
+  /**
+   * Called when the student flips the spin, with its new state — so a site can
+   * persist the choice and pass it back as `spinning`.
+   * @default undefined
+   */
+  onSpinningChange?: (spinning: boolean) => void;
   /**
    * How fast it turns, in molstar's own spin unit. Lower is slower.
    * @default 0.3