react-cheminfo 0.8.0 → 0.10.0

package/src/overlay/ui/OverlaySelect.tsx

@@ -0,0 +1,114 @@
+import { HTMLSelect } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import type { OverlayControlProps, OverlayOption } from './OverlayRow.tsx';
+import { OverlayRow } from './OverlayRow.tsx';
+import { OverlayValueMenu } from './OverlayValueMenu.tsx';
+import { useOverlayPanelShape } from './overlayPanelContext.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** How a picker is drawn. */
+export type OverlaySelectAppearance = 'field' | 'quiet';
+
+/** What {@link OverlaySelect} needs. Use it past four choices. */
+export interface OverlaySelectProps<
+  TValue extends string = string,
+> extends OverlayControlProps {
+  /** The current choice. */
+  value: TValue;
+  /** What may be chosen, in the order offered. */
+  options: ReadonlyArray<OverlayOption<TValue>>;
+  /** Called with the new choice. */
+  onChange: (value: TValue) => void;
+  /**
+   * Whether the picker is drawn as a form field or as a quiet button showing
+   * only its value.
+   *
+   * A settings panel gets `quiet` on its own, because a bordered field beside
+   * borderless switches and steppers is the one shape in the panel that draws
+   * the eye, and it draws it to whichever setting happens to be a list.
+   * @default 'quiet' inside an OverlayPanel, 'field' anywhere else
+   */
+  appearance?: OverlaySelectAppearance;
+}
+
+/**
+ * The picker a card reaches for once the choices stop fitting side by side.
+ *
+ * The options are written out rather than handed to Blueprint's shorthand,
+ * because a choice that does not apply has to keep its place in the list and
+ * say why the pointer cannot take it — and the shorthand has nowhere to put
+ * that sentence.
+ * @param props - See {@link OverlaySelectProps}.
+ * @returns The caption, its help, and the picker.
+ */
+export function OverlaySelect<TValue extends string = string>(
+  props: OverlaySelectProps<TValue>,
+): ReactElement {
+  const {
+    value,
+    options,
+    onChange,
+    label,
+    help,
+    hideLabel = false,
+    disabled = false,
+    testId,
+  } = props;
+  const { metrics } = useOverlaySurface();
+  const panel = useOverlayPanelShape();
+  const { appearance = panel === undefined ? 'field' : 'quiet' } = props;
+
+  if (appearance === 'quiet') {
+    // The menu goes INSIDE the row rather than replacing it: the row is what
+    // holds the name column and hangs the help off it, and a panel whose rows
+    // do not all have that column is not a grid.
+    return (
+      <OverlayRow
+        label={label}
+        help={help}
+        hideLabel={hideLabel}
+        disabled={disabled}
+      >
+        <OverlayValueMenu
+          label={label}
+          value={value}
+          options={options}
+          onChange={onChange}
+          showKey={false}
+          disabled={disabled}
+          testId={testId}
+        />
+      </OverlayRow>
+    );
+  }
+
+  return (
+    <OverlayRow
+      label={label}
+      help={help}
+      hideLabel={hideLabel}
+      disabled={disabled}
+    >
+      <HTMLSelect
+        value={value}
+        disabled={disabled}
+        large={metrics.blueprintSize === 'large'}
+        aria-label={label}
+        data-testid={testId}
+        onChange={(event) => onChange(event.currentTarget.value as TValue)}
+      >
+        {options.map((option) => (
+          <option
+            key={option.value}
+            value={option.value}
+            title={option.title}
+            disabled={option.disabled}
+          >
+            {option.label}
+          </option>
+        ))}
+      </HTMLSelect>
+    </OverlayRow>
+  );
+}

package/src/overlay/ui/OverlaySwatchIcon.tsx

@@ -0,0 +1,126 @@
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** What {@link OverlaySwatchIcon} draws. */
+export interface OverlaySwatchIconProps {
+  /**
+   * The colours the figure is drawn in, in the order it draws them. Hand it
+   * the very colours on the chart: the whole point of this glyph is that a
+   * reader recognises the plot in it without being taught anything.
+   */
+  colors: readonly string[];
+}
+
+/**
+ * The colours of a figure, as the glyph of the control that changes them.
+ *
+ * Every other icon on a bar has to be learned before it means anything. This
+ * one does not: a reader who has just looked at four groups of dots knows what
+ * a row of those four colours opens, which is why the control that picks what
+ * the figure is coloured by wears its palette rather than a paint-pot.
+ *
+ * Past four colours it becomes three and a count. Eight dots inside a
+ * twenty-four pixel button is a smear, and a smear says less about the figure
+ * than three honest colours and the news that there are more.
+ * @param props - See {@link OverlaySwatchIconProps}.
+ * @returns The row of dots.
+ */
+export function OverlaySwatchIcon(props: OverlaySwatchIconProps): ReactElement {
+  const { colors } = props;
+  const { metrics } = useOverlaySurface();
+
+  const shown =
+    colors.length > OVERLAY_SWATCH_DOTS
+      ? OVERLAY_SWATCH_DOTS - 1
+      : colors.length;
+  const rest = colors.length - shown;
+  const size = dotSize(metrics);
+  const dots: ReactElement[] = [];
+  for (let index = 0; index < shown; index++) {
+    const color = colors[index];
+    if (color === undefined) continue;
+    dots.push(
+      <span
+        key={`${index}:${color}`}
+        style={overlaySwatchDotStyle(color, size)}
+      />,
+    );
+  }
+
+  return (
+    <span aria-hidden="true" style={OVERLAY_SWATCH_ROW_STYLE}>
+      {dots}
+      {rest > 0 ? (
+        <span style={overlaySwatchRestStyle(metrics)}>{`+${rest}`}</span>
+      ) : null}
+    </span>
+  );
+}
+
+/** How many dots the glyph holds before the last one becomes a count. */
+const OVERLAY_SWATCH_DOTS = 4;
+
+/** The dots side by side, with the button's own ink for the count. */
+const OVERLAY_SWATCH_ROW_STYLE = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 2,
+} as const satisfies CSSProperties;
+
+/**
+ * One dot.
+ *
+ * Round rather than square, because these stand for the marks on a scatter
+ * rather than for the series of a bar chart.
+ *
+ * The hairline that keeps a pale group visible against the card is drawn only
+ * once the dot is wide enough to carry it: inside a four pixel dot a one pixel
+ * ring is half the dot, and the reader is then shown a grey ring with a speck
+ * of the group's colour in it — which is the one thing this glyph exists not
+ * to do.
+ * @param color - The colour of the group it stands for.
+ * @param size - How wide the dot is.
+ * @returns The dot's rules.
+ */
+function overlaySwatchDotStyle(color: string, size: number): CSSProperties {
+  return {
+    display: 'inline-block',
+    width: size,
+    height: size,
+    borderRadius: '50%',
+    background: color,
+    boxShadow: size >= 6 ? 'inset 0 0 0 1px var(--border)' : undefined,
+  };
+}
+
+/**
+ * The count standing in for the colours that did not fit.
+ *
+ * It takes the button's own ink rather than a colour of its own, so it fades
+ * and lights with the button instead of reading as a fifth group.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The count's rules.
+ */
+function overlaySwatchRestStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    fontSize: Math.max(9, metrics.labelSize - 1),
+    fontVariantNumeric: 'tabular-nums',
+    fontWeight: 600,
+    lineHeight: 1,
+  };
+}
+
+/**
+ * How wide one dot is.
+ *
+ * A sixth of the button, so the row of four fills it the way a glyph would
+ * rather than sitting in the middle of it as four specks.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The dot's width in pixels.
+ */
+function dotSize(metrics: OverlayMetrics): number {
+  return Math.max(4, Math.round(metrics.buttonSize / 6));
+}

package/src/overlay/ui/OverlayToggle.tsx

@@ -0,0 +1,136 @@
+import type { IconName } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+import { Button } from 'react-science/ui';
+
+import type { OverlayControlProps } from './OverlayRow.tsx';
+import { OverlayRow } from './OverlayRow.tsx';
+import { overlaySwatchStyle } from './overlayControlStyles.ts';
+import { useOverlayPanelShape } from './overlayPanelContext.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+import {
+  overlaySwitchKnobStyle,
+  overlaySwitchStyle,
+  overlaySwitchTrack,
+  overlaySwitchTrackStyle,
+} from './overlaySwitchStyles.ts';
+
+/** How a toggle is drawn. */
+export type OverlayToggleAppearance = 'button' | 'switch';
+
+/** What {@link OverlayToggle} needs. */
+export interface OverlayToggleProps extends OverlayControlProps {
+  /** Whether it is on. */
+  checked: boolean;
+  /** Called with the new state. */
+  onChange: (checked: boolean) => void;
+  /**
+   * How it is drawn: a pressed button carrying its own words, or a switch
+   * beside a name in a panel's control column.
+   * @default `'switch'` inside an {@link OverlayPanel}, `'button'` anywhere else
+   */
+  appearance?: OverlayToggleAppearance;
+  /**
+   * Colour of the square in front of the caption. Give it the series' own
+   * colour and a row of toggles becomes the figure's legend, each entry
+   * showing and hiding what it names. Drawn by the button appearance alone.
+   * @default undefined — no square is drawn
+   */
+  swatch?: string;
+  /**
+   * Blueprint glyph in front of the caption, for a toggle short of room. Drawn
+   * by the button appearance alone.
+   * @default undefined
+   */
+  icon?: IconName;
+}
+
+/**
+ * One thing on the figure turned on and off.
+ *
+ * On a bar it is a pressed button, because the same control has to work as a
+ * legend entry — a swatch and a series name that dim when the series is hidden
+ * — and a checkbox beside a colour square reads as two separate claims about
+ * one series. In a panel it is a switch, because a row of grey chips is a row
+ * whose state cannot be read: `One scale for all` drawn as a chip answers the
+ * reader's only question about it — is it on? — with nothing at all, and the
+ * reader has to click it to find out.
+ *
+ * It stays a real `button` reporting `aria-pressed` in both appearances rather
+ * than becoming a checkbox in one of them, since a control that reports its
+ * state one way on a bar and another in a panel is a control a reader who
+ * cannot see it has to learn twice. A native button is also operated by Space
+ * and by Enter for nothing, where a checkbox built out of a `div` has to
+ * reimplement both and usually gets one of them subtly wrong.
+ *
+ * A swatch takes the glyph's place when both are given, since the colour is
+ * what ties the entry to a mark on the chart.
+ * @param props - See {@link OverlayToggleProps}.
+ * @returns The toggle.
+ */
+export function OverlayToggle(props: OverlayToggleProps): ReactElement {
+  const {
+    checked,
+    onChange,
+    label,
+    help,
+    hideLabel = false,
+    disabled = false,
+    testId,
+    swatch,
+    icon,
+  } = props;
+  const { metrics } = useOverlaySurface();
+  const panel = useOverlayPanelShape();
+  const appearance =
+    props.appearance ?? (panel === undefined ? 'button' : 'switch');
+
+  if (appearance === 'switch') {
+    const track = overlaySwitchTrack(metrics);
+    return (
+      <OverlayRow
+        label={label}
+        help={help}
+        hideLabel={hideLabel}
+        disabled={disabled}
+      >
+        <button
+          type="button"
+          aria-pressed={checked}
+          aria-label={label}
+          disabled={disabled}
+          data-testid={testId}
+          style={overlaySwitchStyle(metrics, track, disabled)}
+          onClick={() => onChange(!checked)}
+        >
+          <span style={overlaySwitchTrackStyle(track, checked)}>
+            <span style={overlaySwitchKnobStyle(track, checked)} />
+          </span>
+        </button>
+      </OverlayRow>
+    );
+  }
+
+  return (
+    <OverlayRow label={label} help={help} hideLabel disabled={disabled}>
+      <Button
+        variant="minimal"
+        size={metrics.blueprintSize}
+        active={checked}
+        disabled={disabled}
+        aria-pressed={checked}
+        aria-label={label}
+        title={hideLabel ? label : undefined}
+        icon={
+          swatch === undefined ? (
+            icon
+          ) : (
+            <span style={overlaySwatchStyle(swatch)} />
+          )
+        }
+        text={hideLabel ? undefined : label}
+        data-testid={testId}
+        onClick={() => onChange(!checked)}
+      />
+    </OverlayRow>
+  );
+}

package/src/overlay/ui/OverlayValueButton.tsx

@@ -0,0 +1,149 @@
+import { Icon } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+import { useState } from 'react';
+
+import { OverlaySwatchIcon } from './OverlaySwatchIcon.tsx';
+import { useOverlaySurface } from './overlaySurface.ts';
+import {
+  overlayCaretStyle,
+  overlayValueButtonStyle,
+  overlayValueKeyStyle,
+  overlayValueTextStyle,
+} from './overlayValueStyles.ts';
+
+/** What {@link OverlayValueButton} needs. */
+export interface OverlayValueButtonProps {
+  /**
+   * What the setting is called, in full and phrased as the question the reader
+   * already has: `Colour by`, `Group outlines`. It is never the thing written
+   * on the bar — it goes into `title` and `aria-label` with the value after
+   * it, so a button showing `Species` still announces `Colour by — Species`.
+   */
+  label: string;
+  /**
+   * What the setting is currently on, which is the thing actually written:
+   * `Species`, `95%`. Write the answer rather than the jargon.
+   */
+  value: string;
+  /**
+   * The one word written in front of the value on a roomy bar.
+   * @default the label, which is right wherever the name is already one word
+   */
+  keyWord?: string;
+  /**
+   * Whether that key word is written. This is the first thing a narrowing bar
+   * turns off: the name of a setting is read once and its value every time.
+   * @default true
+   */
+  showKey?: boolean;
+  /**
+   * The figure's own colours, drawn as a row of dots in front of the words. A
+   * reader who has just looked at four groups of dots recognises them without
+   * being taught anything, which is worth more than any paint-pot glyph.
+   * @default undefined — no dots are drawn
+   */
+  swatches?: readonly string[];
+  /**
+   * Whether the choices behind it are showing.
+   * @default false
+   */
+  active?: boolean;
+  /**
+   * Whether it cannot be pressed.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Why it cannot be pressed, which the pointer is told in place of the name.
+   * A greyed control that does not say why is worse than one that is missing.
+   * @default undefined — the pointer is still told the name and the value
+   */
+  disabledReason?: string;
+  /**
+   * Whether pressing it opens a menu, which is what tells a screen reader
+   * there is more behind the words than a press.
+   * @default false
+   */
+  opensMenu?: boolean;
+  /**
+   * Called when it is pressed. Leave it out inside a popover, which listens on
+   * the wrapper it puts around the button and would otherwise be told twice.
+   * @default undefined — nothing of its own happens
+   */
+  onClick?: () => void;
+  /**
+   * Value of the `data-testid` attribute.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * 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
+ * `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}.
+ * @returns The button.
+ */
+export function OverlayValueButton(
+  props: OverlayValueButtonProps,
+): ReactElement {
+  const { label, value, keyWord = label, showKey = true, swatches } = props;
+  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 name = `${label} — ${value}`;
+  const told = disabled && disabledReason !== undefined ? disabledReason : name;
+
+  return (
+    <button
+      type="button"
+      title={told}
+      aria-label={name}
+      aria-haspopup={opensMenu ? 'menu' : undefined}
+      aria-expanded={opensMenu ? active : undefined}
+      disabled={disabled}
+      data-testid={testId}
+      style={overlayValueButtonStyle(metrics, {
+        hovered,
+        focused,
+        active,
+        disabled,
+      })}
+      onClick={onClick}
+      onPointerEnter={() => setHovered(true)}
+      onPointerLeave={() => setHovered(false)}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+    >
+      {swatches === undefined || swatches.length === 0 ? null : (
+        <OverlaySwatchIcon colors={swatches} />
+      )}
+      {showKey ? <span style={overlayValueKeyStyle()}>{keyWord}</span> : null}
+      <span style={overlayValueTextStyle()}>{value}</span>
+      <span aria-hidden="true" style={overlayCaretStyle()}>
+        <Icon icon="caret-down" size={caretSize(metrics.fontSize)} />
+      </span>
+    </button>
+  );
+}
+
+/**
+ * How big the caret is drawn.
+ *
+ * A little larger than the type it follows, because Blueprint's caret is a
+ * small triangle inside its box and one drawn at the font size reads as a
+ * speck rather than as an invitation to press.
+ * @param fontSize - The size of the words it follows.
+ * @returns The caret's size in pixels.
+ */
+function caretSize(fontSize: number): number {
+  return fontSize + 2;
+}

package/src/overlay/ui/OverlayValueMenu.tsx

@@ -0,0 +1,141 @@
+import type { PopoverNextPlacement } from '@blueprintjs/core';
+import { Menu, MenuDivider, MenuItem, PopoverNext } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { useId, useState } from 'react';
+
+import type { OverlayOption } from './OverlayRow.tsx';
+import { OverlayValueButton } from './OverlayValueButton.tsx';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** What {@link OverlayValueMenu} needs. */
+export interface OverlayValueMenuProps<TValue extends string = string> {
+  /**
+   * What the setting is called, in full: `Colour by`, `Group outlines`. It
+   * names the button for the pointer and the screen reader, and it is written
+   * over the menu as its heading — so a reader who opened it on a guess is
+   * told what they have opened before they choose.
+   */
+  label: string;
+  /** The current choice, whose own label is what the button writes. */
+  value: TValue;
+  /** What may be chosen, in the order offered. */
+  options: ReadonlyArray<OverlayOption<TValue>>;
+  /** Called with the new choice. */
+  onChange: (value: TValue) => void;
+  /**
+   * The one word written in front of the value on a roomy bar.
+   * @default the label
+   */
+  keyWord?: string;
+  /**
+   * Whether that key word is written.
+   * @default true
+   */
+  showKey?: boolean;
+  /**
+   * The figure's own colours, drawn as a row of dots in front of the words.
+   * @default undefined — no dots are drawn
+   */
+  swatches?: readonly string[];
+  /**
+   * Whether the setting cannot be reached at all.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Why it cannot be reached, which the pointer is told in place of the name.
+   * @default undefined — the pointer is still told the name and the value
+   */
+  disabledReason?: string;
+  /**
+   * Which way the menu opens. Away from the nearest edge of the figure, so the
+   * choices are not the thing that pushes the reader off the picture.
+   * @default 'bottom-end'
+   */
+  placement?: PopoverNextPlacement;
+  /**
+   * Value of the `data-testid` attribute of the button.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * A setting written as its value, whose choices are a menu behind it.
+ *
+ * It is what a picker becomes on a bar with no room for captions: the same
+ * choices, in the same order, with the one in force ticked. It takes the very
+ * options the picker takes, so a bar swaps one for the other without reshaping
+ * anything it holds — and unlike the picker it answers the reader's question
+ * before it is opened, because the answer is what is written on it.
+ * @param props - See {@link OverlayValueMenuProps}.
+ * @returns The button and its menu.
+ */
+export function OverlayValueMenu<TValue extends string = string>(
+  props: OverlayValueMenuProps<TValue>,
+): ReactElement {
+  const { label, value, options, onChange, keyWord, showKey } = props;
+  const { swatches, disabled = false, disabledReason } = props;
+  const { placement = 'bottom-end', testId } = props;
+  const { metrics } = useOverlaySurface();
+  const headingId = useId();
+  const [open, setOpen] = useState(false);
+
+  let written: string = value;
+  for (const option of options) {
+    if (option.value === value) written = option.label;
+  }
+
+  return (
+    <PopoverNext
+      isOpen={open}
+      disabled={disabled}
+      placement={placement}
+      onInteraction={(next) => setOpen(next)}
+      content={
+        <Menu
+          role="listbox"
+          aria-labelledby={headingId}
+          size={metrics.blueprintSize}
+          style={OVERLAY_VALUE_MENU_STYLE}
+        >
+          <MenuDivider title={label} titleId={headingId} />
+          {options.map((option) => (
+            <MenuItem
+              key={option.value}
+              roleStructure="listoption"
+              selected={option.value === value}
+              text={option.label}
+              htmlTitle={option.title}
+              disabled={option.disabled}
+              onClick={() => onChange(option.value)}
+            />
+          ))}
+        </Menu>
+      }
+    >
+      <OverlayValueButton
+        label={label}
+        value={written}
+        keyWord={keyWord}
+        showKey={showKey}
+        swatches={swatches}
+        active={open}
+        disabled={disabled}
+        disabledReason={disabledReason}
+        testId={testId}
+        opensMenu
+      />
+    </PopoverNext>
+  );
+}
+
+/**
+ * The menu the value opens.
+ *
+ * It has a floor width rather than hugging its longest choice, because a menu
+ * of three short words opens as a sliver the reader has to aim at.
+ */
+const OVERLAY_VALUE_MENU_STYLE: CSSProperties = {
+  minWidth: 168,
+};