react-cheminfo 0.9.0 → 0.10.0

package/src/overlay/ui/OverlayChip.tsx

@@ -0,0 +1,181 @@
+import type { PopoverNextPlacement } from '@blueprintjs/core';
+import { Icon, PopoverNext } from '@blueprintjs/core';
+import type { ReactElement, ReactNode } from 'react';
+import { Fragment, useId, useState } from 'react';
+
+import { OverlaySwatchIcon } from './OverlaySwatchIcon.tsx';
+import { overlayGroupTitleStyle } from './overlayControlStyles.ts';
+import { overlayPanelStyle } from './overlayStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+import {
+  overlayCaretStyle,
+  overlayChipSeparatorStyle,
+  overlayChipStyle,
+  overlayValueTextStyle,
+} from './overlayValueStyles.ts';
+
+/** One setting a chip reads out. */
+export interface OverlayChipSetting {
+  /**
+   * What the setting is called, in full: `Colour by`, `Group outlines`. It is
+   * never written on the chip — it is what the chip announces, so a screen
+   * reader is told which question each value answers.
+   */
+  label: string;
+  /** What the setting is currently on, which is what the chip writes. */
+  value: string;
+  /**
+   * The figure's own colours, drawn as a row of dots at the head of the chip.
+   * @default undefined — no dots are drawn
+   */
+  swatches?: readonly string[];
+}
+
+/** What {@link OverlayChip} needs. */
+export interface OverlayChipProps {
+  /** What the settings are called together, written over the panel it opens. */
+  label: string;
+  /** The settings it reads out, in the order they are written. */
+  settings: readonly OverlayChipSetting[];
+  /**
+   * The controls behind it, each with its own caption — the same controls the
+   * bar holds when it has room for them, rather than a reduced set.
+   */
+  children: ReactNode;
+  /**
+   * Whether none of the settings can be reached.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Which way the panel opens.
+   * @default 'bottom-end'
+   */
+  placement?: PopoverNextPlacement;
+  /**
+   * Value of the `data-testid` attribute of the chip.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * Several settings gathered into one rounded chip that still reads them out.
+ *
+ * This is what a narrow bar folds its settings into, and the whole argument
+ * for it is that it is not a cog. A cog says only that there are settings; a
+ * reader looking at a scatter of coloured dots on a phone wants to know what
+ * the colours mean and how wide the outlines are drawn, and `Species · 95%`
+ * answers both without being opened. What the fold actually buys is one
+ * button's padding and one caret per setting swallowed — which is why the
+ * words survive it and only the boxes around them go.
+ * @param props - See {@link OverlayChipProps}.
+ * @returns The chip and its panel.
+ */
+export function OverlayChip(props: OverlayChipProps): ReactElement {
+  const { label, settings, children, disabled = false } = props;
+  const { placement = 'bottom-end', testId } = props;
+  const { metrics } = useOverlaySurface();
+  const headingId = useId();
+  const [open, setOpen] = useState(false);
+  const [hovered, setHovered] = useState(false);
+  const [focused, setFocused] = useState(false);
+
+  const swatches = leadingSwatches(settings);
+  const name = announce(settings);
+
+  return (
+    <PopoverNext
+      isOpen={open}
+      disabled={disabled}
+      placement={placement}
+      onInteraction={(next) => setOpen(next)}
+      content={
+        <div
+          role="group"
+          aria-labelledby={headingId}
+          style={overlayPanelStyle(metrics)}
+        >
+          <span id={headingId} style={overlayGroupTitleStyle(metrics)}>
+            {label}
+          </span>
+          {children}
+        </div>
+      }
+    >
+      <button
+        type="button"
+        title={name}
+        aria-label={name}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        disabled={disabled}
+        data-testid={testId}
+        style={overlayChipStyle(metrics, {
+          hovered,
+          focused,
+          active: open,
+          disabled,
+        })}
+        onPointerEnter={() => setHovered(true)}
+        onPointerLeave={() => setHovered(false)}
+        onFocus={() => setFocused(true)}
+        onBlur={() => setFocused(false)}
+      >
+        {swatches === undefined ? null : (
+          <OverlaySwatchIcon colors={swatches} />
+        )}
+        {settings.map((setting, index) => (
+          <Fragment key={setting.label}>
+            {index === 0 ? null : (
+              <span
+                aria-hidden="true"
+                style={overlayChipSeparatorStyle(metrics)}
+              />
+            )}
+            <span style={overlayValueTextStyle()}>{setting.value}</span>
+          </Fragment>
+        ))}
+        <span aria-hidden="true" style={overlayCaretStyle()}>
+          <Icon icon="caret-down" size={metrics.fontSize + 2} />
+        </span>
+      </button>
+    </PopoverNext>
+  );
+}
+
+/**
+ * What the chip is called, which is every setting spelled out in full.
+ *
+ * The chip writes bare values, so a reader who cannot see it would otherwise
+ * be told `Species · 95%` and left to guess which question each answers.
+ * @param settings - The settings it reads out.
+ * @returns The name.
+ */
+function announce(settings: readonly OverlayChipSetting[]): string {
+  let name = '';
+  for (const setting of settings) {
+    if (name !== '') name += ', ';
+    name += `${setting.label} — ${setting.value}`;
+  }
+  return name;
+}
+
+/**
+ * The colours drawn at the head of the chip.
+ *
+ * The first setting that has any, and only that one: two rows of dots inside
+ * one chip read as one palette of eight colours, which is the one thing this
+ * glyph exists not to say.
+ * @param settings - The settings it reads out.
+ * @returns The colours, or nothing.
+ */
+function leadingSwatches(
+  settings: readonly OverlayChipSetting[],
+): readonly string[] | undefined {
+  for (const setting of settings) {
+    const { swatches } = setting;
+    if (swatches !== undefined && swatches.length > 0) return swatches;
+  }
+  return undefined;
+}

package/src/overlay/ui/OverlayDivider.tsx

@@ -0,0 +1,24 @@
+import type { ReactElement } from 'react';
+
+import { overlayDividerStyle } from './overlayControlStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/**
+ * A hairline between two clusters of controls.
+ *
+ * It is a real separator rather than a decorative line, so a reader moving
+ * through the card with a screen reader is told where one group of controls
+ * ends — which is the whole reason the line is there for everyone else.
+ * @returns The rule.
+ */
+export function OverlayDivider(): ReactElement {
+  const { metrics } = useOverlaySurface();
+
+  return (
+    <span
+      role="separator"
+      aria-orientation="vertical"
+      style={overlayDividerStyle(metrics)}
+    />
+  );
+}

package/src/overlay/ui/OverlayGroup.tsx

@@ -0,0 +1,157 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useId } from 'react';
+
+import type { HelpContent } from '../../help/ui/HelpBody.tsx';
+import { HelpTooltip } from '../../help/ui/HelpTooltip.tsx';
+
+import {
+  overlayGroupStyle,
+  overlayGroupTitleStyle,
+} from './overlayControlStyles.ts';
+import { useOverlayPanelShape } from './overlayPanelContext.ts';
+import {
+  overlaySectionHeadingStyle,
+  overlaySectionStyle,
+} from './overlayPanelStyles.ts';
+import {
+  OVERLAY_HELP_NAME_STYLE,
+  overlayStackedRowStyle,
+} from './overlayRowStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** What {@link OverlayGroup} needs. */
+export interface OverlayGroupProps {
+  /** The controls it holds. */
+  children: ReactNode;
+  /**
+   * What the cluster is about, written over it in small capitals. In a panel
+   * this is the section heading, and it is worth reaching for only past about
+   * four rows: three settings under two headings is a panel that has been
+   * filed rather than laid out. Nothing enforces that — a panel is allowed to
+   * be wrong about its own length — but it is the line to hold.
+   * @default undefined — the controls are drawn with no heading
+   */
+  label?: string;
+  /**
+   * What the cluster is for, in a sentence. Like a control's own help it hangs
+   * off the heading, which is underlined with dots to say so.
+   * @default undefined
+   */
+  help?: HelpContent;
+  /**
+   * Whether a hairline is drawn above the heading. Turn it off on the first
+   * section of a panel: a rule immediately under the panel header's own rule
+   * reads as a doubled line rather than as a division. Only consulted in a
+   * panel.
+   * @default true
+   */
+  divider?: boolean;
+  /**
+   * How the controls inside are stacked. A row wraps as one unit, so a cluster
+   * never breaks across two lines of the card mid-thought. Only consulted on a
+   * bar; a section of a panel is always a column.
+   * @default 'row'
+   */
+  direction?: 'row' | 'column';
+}
+
+/**
+ * Controls that answer one question, kept together.
+ *
+ * On a bar, two controls that only make sense read together — a mode and the
+ * number it takes — have to move together as the card reflows, or the reader
+ * meets the number on a line of its own with nothing saying what it counts.
+ *
+ * In a panel it is a section instead: a small-capitals heading over a hairline
+ * that gives the eye somewhere to rest on the way down a long list. A heading
+ * is worth adding once the cluster's idea has a name the names inside it do
+ * not already spell out.
+ * @param props - See {@link OverlayGroupProps}.
+ * @returns The cluster.
+ */
+export function OverlayGroup(props: OverlayGroupProps): ReactElement {
+  const { children, label, help, divider = true, direction = 'row' } = props;
+  const { metrics } = useOverlaySurface();
+  const panel = useOverlayPanelShape();
+  const headingId = useId();
+
+  if (panel !== undefined) {
+    if (label === undefined) {
+      return <div style={overlaySectionStyle(metrics)}>{children}</div>;
+    }
+    return (
+      <div
+        role="group"
+        aria-labelledby={headingId}
+        style={overlaySectionStyle(metrics)}
+      >
+        <Explained help={help}>
+          <span
+            id={headingId}
+            className={help === undefined ? undefined : 'help-name'}
+            tabIndex={help === undefined ? undefined : 0}
+            style={overlaySectionHeadingStyle(metrics, {
+              divider,
+              help: help !== undefined,
+            })}
+          >
+            {label}
+          </span>
+        </Explained>
+        {children}
+      </div>
+    );
+  }
+
+  const controls = (
+    <div style={overlayGroupStyle(metrics, direction)}>{children}</div>
+  );
+
+  if (label === undefined) return controls;
+
+  return (
+    <div
+      role="group"
+      aria-labelledby={headingId}
+      style={overlayStackedRowStyle(metrics)}
+    >
+      <Explained help={help}>
+        <span
+          id={headingId}
+          className={help === undefined ? undefined : 'help-name'}
+          tabIndex={help === undefined ? undefined : 0}
+          style={
+            help === undefined
+              ? overlayGroupTitleStyle(metrics)
+              : {
+                  ...overlayGroupTitleStyle(metrics),
+                  ...OVERLAY_HELP_NAME_STYLE,
+                }
+          }
+        >
+          {label}
+        </span>
+      </Explained>
+      {controls}
+    </div>
+  );
+}
+
+/**
+ * A heading, with its explanation behind it when it has one.
+ *
+ * The two shapes a group takes both need this, and writing the conditional
+ * twice is how one of them quietly loses its help.
+ * @param props - The heading and what it explains.
+ * @param props.help - The explanation, or nothing.
+ * @param props.children - The heading.
+ * @returns The heading.
+ */
+function Explained(props: {
+  help: HelpContent | undefined;
+  children: ReactNode;
+}): ReactElement {
+  const { help, children } = props;
+  if (help === undefined) return <>{children}</>;
+  return <HelpTooltip content={help}>{children}</HelpTooltip>;
+}

package/src/overlay/ui/OverlayIconButton.tsx

@@ -0,0 +1,131 @@
+import type { IconName } from '@blueprintjs/core';
+import { Icon } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+import { useState } from 'react';
+
+import { overlayIconButtonStyle } from './overlayControlStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** What {@link OverlayIconButton} needs. */
+export interface OverlayIconButtonProps {
+  /**
+   * The glyph: a Blueprint icon name, or an element of the caller's own — an
+   * inline `<svg>` drawing the very mark the figure draws, which is the one
+   * kind of icon a reader does not have to learn.
+   */
+  icon: IconName | ReactElement;
+  /**
+   * What the setting is called, phrased as the question the reader already
+   * has: `Colour by`, `Group outlines`. It is written into both `title` and
+   * `aria-label`, because a glyph says nothing until it is named — that is the
+   * price of an icon-only bar, and it is paid here rather than left to each
+   * caller to remember.
+   */
+  label: string;
+  /**
+   * What the setting is currently on, written after the name as
+   * `label — value`. Give it wherever there is one: `Colour by — species`
+   * answers the reader's actual question, where `Colour by` alone only tells
+   * them which question the button asks.
+   * @default undefined — the name alone
+   */
+  value?: string;
+  /**
+   * Whether the choices behind it are showing, or the thing it turns on is on.
+   * @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 glyph that does not say why is the one thing worse than a glyph.
+   * @default undefined — the pointer is still told the name
+   */
+  disabledReason?: string;
+  /**
+   * Whether pressing it opens a menu. Its state is then announced as a menu
+   * that is open or shut rather than as a button that is pressed, which is
+   * what tells a screen reader there is more behind it.
+   * @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;
+}
+
+/**
+ * One setting reduced to its glyph.
+ *
+ * A bar of named controls over an embedded figure spends more of the picture
+ * on its own words than the figure spends on the data, so on the bar a setting
+ * is a glyph and its name is what the pointer and the screen reader are told.
+ * That trade is only honest while the name is always there, which is why the
+ * label is required rather than optional and why it carries the current value
+ * with it: an icon nobody can name is a control nobody presses.
+ * @param props - See {@link OverlayIconButtonProps}.
+ * @returns The button.
+ */
+export function OverlayIconButton(props: OverlayIconButtonProps): ReactElement {
+  const { icon, label, value, active = false, disabled = false } = props;
+  const { disabledReason, opensMenu = false, onClick, testId } = props;
+  const { metrics } = useOverlaySurface();
+  const [lit, setLit] = useState(false);
+
+  const name = value === undefined ? label : `${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}
+      aria-pressed={opensMenu ? undefined : active}
+      disabled={disabled}
+      data-testid={testId}
+      style={overlayIconButtonStyle(metrics, {
+        hovered: lit,
+        active,
+        disabled,
+      })}
+      onClick={onClick}
+      onPointerEnter={() => setLit(true)}
+      onPointerLeave={() => setLit(false)}
+      onFocus={() => setLit(true)}
+      onBlur={() => setLit(false)}
+    >
+      {typeof icon === 'string' ? (
+        <Icon icon={icon} size={glyphSize(metrics.buttonSize)} />
+      ) : (
+        icon
+      )}
+    </button>
+  );
+}
+
+/**
+ * How big the glyph is drawn inside the button.
+ *
+ * A little over half the button, which leaves the ring of empty space that
+ * makes a bare glyph read as something pressable rather than as a mark printed
+ * on the bar.
+ * @param buttonSize - The side of the button.
+ * @returns The glyph's size in pixels.
+ */
+function glyphSize(buttonSize: number): number {
+  return Math.max(12, Math.round(buttonSize * 0.55));
+}

package/src/overlay/ui/OverlayInfo.tsx

@@ -0,0 +1,92 @@
+import type { PopoverNextProps } from '@blueprintjs/core';
+import { PopoverNext } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+import { useState } from 'react';
+
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+
+import { OverlayIconButton } from './OverlayIconButton.tsx';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** What {@link OverlayInfo} holds. */
+export interface OverlayInfoProps {
+  /**
+   * The explanation, in the reader's own words: what a mark is before what an
+   * axis is, one short paragraph rather than a manual.
+   */
+  children: ReactNode;
+  /**
+   * What the glyph is called, for the pointer and for a screen reader. Phrase
+   * it as the question the reader has, not as the name of a feature.
+   * @default 'What am I looking at?'
+   */
+  label?: string;
+  /**
+   * Which side the explanation opens on.
+   * @default 'bottom-end'
+   */
+  placement?: PopoverNextProps['placement'];
+  /**
+   * Value of the `data-testid` attribute of the glyph.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * The question mark that hands the figure's own explanation back on request.
+ *
+ * A figure embedded in somebody else's page cannot spend three lines of that
+ * page standing a paragraph under itself, and a paragraph deleted for room is
+ * a reader left to guess what they are looking at. So the sentence is kept and
+ * the vertical space is not: it waits behind one glyph in the bar, where a
+ * reader who wants it can open it and everybody else never pays for it.
+ *
+ * The glyph is the domain's own icon button, the same one the cog beside it
+ * is, so the two read as a pair of marks on the bar rather than as two
+ * buttons from different families that happen to sit next to each other.
+ * @param props - See {@link OverlayInfoProps}.
+ * @returns The glyph and its explanation.
+ */
+export function OverlayInfo(props: OverlayInfoProps): ReactElement {
+  const { children, label = 'What am I looking at?' } = props;
+  const { placement = 'bottom-end', testId } = props;
+  const { metrics } = useOverlaySurface();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <PopoverNext
+      placement={placement}
+      onInteraction={(next) => setOpen(next)}
+      content={<div style={explanationStyle(metrics)}>{children}</div>}
+    >
+      <OverlayIconButton
+        icon="help"
+        label={label}
+        active={open}
+        testId={testId}
+        opensMenu
+      />
+    </PopoverNext>
+  );
+}
+
+/**
+ * The paragraph the glyph opens.
+ *
+ * It is capped short of the figure's own width, because a sentence that runs
+ * the full width of a wide chart is a sentence the eye loses the start of on
+ * the way back from the end of each line.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The explanation's rules.
+ */
+function explanationStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    maxWidth: 320,
+    padding: `${metrics.paddingY + 4}px ${metrics.paddingX + 4}px`,
+    color: 'var(--text)',
+    fontSize: metrics.labelSize + 1,
+    lineHeight: 1.4,
+    textWrap: 'pretty',
+  };
+}

package/src/overlay/ui/OverlayLayer.tsx

@@ -0,0 +1,118 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import type { OverlayDensity } from '../core/overlayMetrics.ts';
+import { overlayMetrics } from '../core/overlayMetrics.ts';
+
+import { OVERLAY_LAYER_STYLE } from './overlayStyles.ts';
+import type { OverlaySurface } from './overlaySurface.ts';
+import { OverlaySurfaceContext, useCoarsePointer } from './overlaySurface.ts';
+
+/** What {@link OverlayLayer} needs. */
+export interface OverlayLayerProps {
+  /** The cards, legends and readouts that float over the figure. */
+  children: ReactNode;
+  /**
+   * How tightly every card inside packs its controls. A coarse pointer wins
+   * over this, whatever it says.
+   * @default 'comfortable'
+   */
+  density?: OverlayDensity;
+  /**
+   * Width of the figure, in pixels, normally from `useContainerSize`. It is
+   * what decides whether a card folds; zero keeps every card expanded.
+   * @default 0
+   */
+  width?: number;
+  /**
+   * Whether the figure is repainting — a lasso being dragged, a canvas
+   * animating.
+   * @default false
+   */
+  busy?: boolean;
+  /**
+   * Whether the cards are awake. Left out, the layer wakes them while the
+   * pointer is anywhere over the figure or a control inside holds the focus,
+   * which is what lets a card rest without becoming a puzzle.
+   * @default undefined — the layer watches the pointer and the focus itself
+   */
+  awake?: boolean;
+  /**
+   * Class the layer carries, in addition to `overlay-layer`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * The inert layer a figure's floating chrome lives in.
+ *
+ * It covers the figure and lets every pointer event through, so a lasso
+ * started under a card still starts; only the cards themselves take the
+ * pointer back. Everything they share — the measurements, whether they are
+ * awake, whether the figure is repainting — is settled here once, so two cards
+ * over the same figure cannot disagree.
+ *
+ * It is marked as chrome, so that saving the figure saves the picture and not
+ * the cog sitting in its corner: the glyph of a control is an `<svg>` like any
+ * chart, and nothing else on the page could tell the two apart.
+ * @param props - See {@link OverlayLayerProps}.
+ * @returns The layer.
+ */
+export function OverlayLayer(props: OverlayLayerProps): ReactElement {
+  const {
+    children,
+    density = 'comfortable',
+    width = 0,
+    busy = false,
+    awake,
+    className,
+  } = props;
+
+  const layer = useRef<HTMLDivElement>(null);
+  const [pointerOverFigure, setPointerOverFigure] = useState(false);
+  const [focusInside, setFocusInside] = useState(false);
+  const pointer = useCoarsePointer() ? 'coarse' : 'fine';
+  const watchingPointer = awake === undefined;
+
+  useEffect(() => {
+    const figure = layer.current?.parentElement;
+    if (!watchingPointer || figure === null || figure === undefined) return;
+    const enter = () => setPointerOverFigure(true);
+    const leave = () => setPointerOverFigure(false);
+    figure.addEventListener('pointerenter', enter);
+    figure.addEventListener('pointerleave', leave);
+    return () => {
+      figure.removeEventListener('pointerenter', enter);
+      figure.removeEventListener('pointerleave', leave);
+    };
+  }, [watchingPointer]);
+
+  const surface = useMemo<OverlaySurface>(
+    () => ({
+      metrics: overlayMetrics(density, pointer),
+      awake: awake ?? (pointerOverFigure || focusInside),
+      busy,
+      width,
+      pointer,
+    }),
+    [density, pointer, awake, pointerOverFigure, focusInside, busy, width],
+  );
+
+  return (
+    <div
+      ref={layer}
+      className={
+        className === undefined ? 'overlay-layer' : `overlay-layer ${className}`
+      }
+      style={OVERLAY_LAYER_STYLE}
+      data-figure="chrome"
+      onFocus={() => setFocusInside(true)}
+      onBlur={() => setFocusInside(false)}
+    >
+      <OverlaySurfaceContext.Provider value={surface}>
+        {children}
+      </OverlaySurfaceContext.Provider>
+    </div>
+  );
+}