react-cheminfo 0.9.0 → 0.11.0

package/src/overlay/ui/OverlayAction.tsx

@@ -0,0 +1,66 @@
+import type { IconName, Intent } 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 { useOverlaySurface } from './overlaySurface.ts';
+
+/** What {@link OverlayAction} needs. */
+export interface OverlayActionProps extends Omit<
+  OverlayControlProps,
+  'label' | 'hideLabel'
+> {
+  /** What the button reads: a verb and its object, `Zoom to selection`. */
+  text: string;
+  /** Called when it is pressed. */
+  onClick: () => void;
+  /**
+   * A glyph before the text. Never instead of it: an icon-only control in a
+   * floating card is a control nobody presses.
+   * @default undefined
+   */
+  icon?: IconName;
+  /**
+   * What the button means, which is not whether it is pressed.
+   * @default 'none'
+   */
+  intent?: Intent;
+}
+
+/**
+ * The one control here that does something rather than changing something.
+ *
+ * It carries no caption of its own because its words already are one — a verb
+ * and its object — and a caption in front of a button that reads `Zoom to
+ * selection` says the same thing twice in a card that has room for neither.
+ * @param props - See {@link OverlayActionProps}.
+ * @returns The button, with its help.
+ */
+export function OverlayAction(props: OverlayActionProps): ReactElement {
+  const {
+    text,
+    onClick,
+    icon,
+    intent = 'none',
+    help,
+    disabled = false,
+    testId,
+  } = props;
+  const { metrics } = useOverlaySurface();
+
+  return (
+    <OverlayRow label={text} help={help} hideLabel disabled={disabled}>
+      <Button
+        variant="minimal"
+        size={metrics.blueprintSize}
+        intent={intent}
+        icon={icon}
+        text={text}
+        disabled={disabled}
+        data-testid={testId}
+        onClick={onClick}
+      />
+    </OverlayRow>
+  );
+}

package/src/overlay/ui/OverlayBar.tsx

@@ -0,0 +1,188 @@
+import type { IconName } from '@blueprintjs/core';
+import type { ReactElement, ReactNode } from 'react';
+import { useState } from 'react';
+
+import type { OverlayPlacement } from '../core/overlayPlacement.ts';
+
+import { OverlayBarCard } from './OverlayBarCard.tsx';
+import { OverlayBarStrip } from './OverlayBarStrip.tsx';
+import { overlayBarFolded, useFoldReport } from './overlayBarShape.ts';
+import { OVERLAY_RESTING_OPACITY } from './overlayStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** What {@link OverlayBar} needs. */
+export interface OverlayBarProps {
+  /**
+   * The controls that stay on screen. Keep it to one or two in a floating
+   * card: a third is already a panel, and a panel over a figure hides the
+   * figure. A stretched bar holds its tab strip here, at the start of the row.
+   */
+  children: ReactNode;
+  /**
+   * What sits at the far end of the row: the controls belonging to whatever
+   * the figure is currently showing. They are the first thing to go when the
+   * figure is too narrow for both ends, folding in behind the button.
+   * @default undefined — the bar's end holds only its glyphs
+   */
+  end?: ReactNode;
+  /**
+   * The glyph-sized tools that act on the figure rather than change how it is
+   * drawn — saving it as a file, printing it. They ride beside the `?` at the
+   * end of the row and, on a stretched bar, never fold: a tool is one button
+   * wide already, and a reader who cannot find the one that takes the figure
+   * away concludes the figure cannot be taken away.
+   * @default undefined — the bar carries no tools
+   */
+  tools?: ReactNode;
+  /**
+   * The one control drawn at the end whatever the width — the `?` opening the
+   * figure's own explanation. It never folds, because a reader short of room
+   * is exactly the reader who has not been told what they are looking at.
+   * @default undefined — the bar carries no glyph
+   */
+  info?: ReactNode;
+  /**
+   * What opens behind the button at the end of the bar — everything an expert
+   * changes and a reader never does. This is where a control goes unless
+   * somebody argued for putting it in the strip.
+   * @default undefined — the bar carries no button
+   */
+  more?: ReactNode;
+  /**
+   * Where it sits. Pick the corner the data leaves emptiest, which
+   * `emptiestCorner` answers from the points themselves, or `stretch` for the
+   * settings bar of an embedded figure, which spans the width above it.
+   * @default 'top-right'
+   */
+  placement?: OverlayPlacement;
+  /**
+   * What the group of controls is called, for a reader arriving by tab and for
+   * the button the bar folds into.
+   * @default 'Options'
+   */
+  label?: string;
+  /**
+   * How opaque the bar is while nothing is pointing at the figure. Never below
+   * about 0.6: a control the reader cannot see is a control they will not look
+   * for, and only the ground fades — the text is always at full strength. `1`
+   * pins it, which is what a figure about to be screenshotted wants. A
+   * stretched bar ignores it: its ground is chrome rather than something laid
+   * over the picture, and chrome that fades reads as a fault.
+   * @default 0.74
+   */
+  restingOpacity?: number;
+  /**
+   * Whether the bar is reduced to a button opening the same controls in a
+   * popover. Left out, it folds on its own once the figure is narrower than
+   * `collapseBelow`.
+   * @default undefined — the bar decides from the figure's width
+   */
+  collapsed?: boolean;
+  /**
+   * Whether it starts folded, for a bar the reader may open and close.
+   * @default false
+   */
+  defaultCollapsed?: boolean;
+  /**
+   * Called when the reader opens or closes it.
+   * @default undefined
+   */
+  onCollapsedChange?: (collapsed: boolean) => void;
+  /**
+   * Figure width, in pixels, under which the bar folds on its own.
+   * @default 420
+   */
+  collapseBelow?: number;
+  /**
+   * Blueprint glyph of the button that opens the rest. A cog rather than an
+   * ellipsis, because once the bar folds that button holds every control and
+   * not only the second tier.
+   * @default 'cog'
+   */
+  moreIcon?: IconName;
+  /**
+   * Whether what opens behind that button is drawn with the card's own padding
+   * around it. Turn it off when `more` is an {@link OverlayPanel}, which
+   * brings its own: nested inside a padded surface a panel's header rule stops
+   * short of both edges and reads as a mis-drawn line rather than as a header.
+   * @default true
+   */
+  morePadded?: boolean;
+  /**
+   * Value of the `data-testid` attribute of the card, for the end-to-end tests.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * The controls of a figure: a small card floating in one of its corners, or
+ * one bar spanning the width above it.
+ *
+ * Which of the two it is, is the whole of the decision made here — the shapes
+ * themselves are drawn by {@link OverlayBarCard} and {@link OverlayBarStrip},
+ * because a card that hides in a corner and a strip that spans the width agree
+ * on what they hold and on nothing about how they sit. A stretched bar is what
+ * an embedded figure wants, where a floating card would spend the host's page
+ * twice — once on the chrome and once on the data the chrome is covering.
+ * @param props - See {@link OverlayBarProps}.
+ * @returns The bar.
+ */
+export function OverlayBar(props: OverlayBarProps): ReactElement {
+  const { children, end, tools, info, more } = props;
+  const { placement = 'top-right' } = props;
+  const { label = 'Options', restingOpacity = OVERLAY_RESTING_OPACITY } = props;
+  const { collapsed, defaultCollapsed = false, onCollapsedChange } = props;
+  const { collapseBelow = 420, moreIcon = 'cog', testId } = props;
+  const { morePadded = true } = props;
+  const { width } = useOverlaySurface();
+  const [startedFolded] = useState(defaultCollapsed);
+
+  const folded = overlayBarFolded({
+    collapsed,
+    startedFolded,
+    width,
+    collapseBelow,
+  });
+  useFoldReport(
+    folded,
+    collapsed === undefined ? onCollapsedChange : undefined,
+  );
+
+  if (placement === 'stretch') {
+    return (
+      <OverlayBarStrip
+        end={end}
+        tools={tools}
+        info={info}
+        more={more}
+        placement={placement}
+        label={label}
+        moreIcon={moreIcon}
+        morePadded={morePadded}
+        folded={folded}
+        testId={testId}
+      >
+        {children}
+      </OverlayBarStrip>
+    );
+  }
+
+  return (
+    <OverlayBarCard
+      end={end}
+      tools={tools}
+      info={info}
+      more={more}
+      placement={placement}
+      label={label}
+      moreIcon={moreIcon}
+      morePadded={morePadded}
+      folded={folded}
+      restingOpacity={restingOpacity}
+      testId={testId}
+    >
+      {children}
+    </OverlayBarCard>
+  );
+}

package/src/overlay/ui/OverlayBarButton.tsx

@@ -0,0 +1,83 @@
+import type { IconName, PopoverNextPlacement } from '@blueprintjs/core';
+import { PopoverNext } from '@blueprintjs/core';
+import type { ReactElement, ReactNode } from 'react';
+import { useState } from 'react';
+
+import type { OverlayPlacement } from '../core/overlayPlacement.ts';
+
+import { OverlayIconButton } from './OverlayIconButton.tsx';
+import { overlayPanelStyle } from './overlayStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** What {@link OverlayBarButton} opens. */
+export interface OverlayBarButtonProps {
+  /**
+   * The controls it holds: whatever has folded away, then the second tier —
+   * everything an expert changes and a reader never does.
+   */
+  children: ReactNode;
+  /** Where the bar sits, which is what decides the way the panel opens. */
+  placement: OverlayPlacement;
+  /** What the button is called, for the pointer and for a screen reader. */
+  label: string;
+  /** Its glyph. */
+  icon: IconName;
+  /**
+   * Whether the panel is drawn with the card's own padding around it. Turn it
+   * off for an {@link OverlayPanel}, which brings its own: nested inside a
+   * padded surface a panel's header rule stops short of both edges and reads
+   * as a mis-drawn line rather than as a header.
+   * @default true
+   */
+  padded?: boolean;
+}
+
+/**
+ * The button at the end of a bar, and the panel behind it.
+ *
+ * Both shapes of bar draw this one, so a reader who has opened the controls of
+ * a floating card knows where the controls of an embedded figure are. It is
+ * the domain's own icon button rather than a general one, which is what keeps
+ * it the same weight of ink as the glyph beside it and lets it say, while the
+ * panel is open, that it is the thing holding the panel open.
+ * @param props - See {@link OverlayBarButtonProps}.
+ * @returns The button and its panel.
+ */
+export function OverlayBarButton(props: OverlayBarButtonProps): ReactElement {
+  const { children, placement, label, icon, padded = true } = props;
+  const { metrics } = useOverlaySurface();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <PopoverNext
+      placement={POPOVER_PLACEMENTS[placement]}
+      onInteraction={(next) => setOpen(next)}
+      content={
+        padded ? (
+          <div style={overlayPanelStyle(metrics)}>{children}</div>
+        ) : (
+          <>{children}</>
+        )
+      }
+    >
+      <OverlayIconButton icon={icon} label={label} active={open} opensMenu />
+    </PopoverNext>
+  );
+}
+
+/**
+ * Which way the panel opens, per placement.
+ *
+ * Away from the nearest edge in both axes, so the panel that opens is never
+ * the thing that pushes the reader's attention off the figure. A docked bar
+ * opens over the figure, which is the only direction it has.
+ */
+const POPOVER_PLACEMENTS: Record<OverlayPlacement, PopoverNextPlacement> = {
+  'top-left': 'bottom-start',
+  'top-right': 'bottom-end',
+  'bottom-left': 'top-start',
+  'bottom-right': 'top-end',
+  above: 'bottom-end',
+  below: 'top-end',
+  stretch: 'bottom-end',
+};

package/src/overlay/ui/OverlayBarCard.tsx

@@ -0,0 +1,78 @@
+import type { ReactElement } from 'react';
+
+import { OverlayBarButton } from './OverlayBarButton.tsx';
+import type { OverlayBarShapeProps } from './overlayBarShape.ts';
+import {
+  overlayCardStyle,
+  overlayContentStyle,
+  overlayGroundStyle,
+  overlayRestingOpacity,
+} from './overlayStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** What {@link OverlayBarCard} needs on top of the shape both bars share. */
+export interface OverlayBarCardProps extends OverlayBarShapeProps {
+  /** How opaque the ground is while nothing is pointing at the figure. */
+  restingOpacity: number;
+}
+
+/**
+ * The small card of controls floating in a corner of a figure.
+ *
+ * It rests at three quarters strength and wakes when the pointer reaches the
+ * figure or the keyboard reaches one of its controls; only the ground fades,
+ * never the text, and the tab order is the same whether it is resting or
+ * awake, so the fade is a courtesy to the eye and never a gate on the
+ * interaction.
+ *
+ * Folded, it is the button alone: a card has only the one tier, and a corner
+ * of a narrow figure is not somewhere half a strip of controls can live — the
+ * tools fold away with the controls, since what they act on is the very figure
+ * the card would then be covering.
+ * @param props - See {@link OverlayBarCardProps}.
+ * @returns The card.
+ */
+export function OverlayBarCard(props: OverlayBarCardProps): ReactElement {
+  const { children, end, tools, info, more, placement, label } = props;
+  const { moreIcon, morePadded, folded, testId, restingOpacity } = props;
+  const { metrics, awake, busy } = useOverlaySurface();
+
+  const opener =
+    folded || more !== undefined ? (
+      <OverlayBarButton
+        placement={placement}
+        label={label}
+        icon={moreIcon}
+        padded={morePadded}
+      >
+        {folded ? children : null}
+        {more}
+      </OverlayBarButton>
+    ) : null;
+
+  return (
+    <div style={overlayCardStyle(placement, metrics)} data-testid={testId}>
+      <div
+        style={overlayGroundStyle(
+          awake ? 1 : overlayRestingOpacity(restingOpacity),
+          busy,
+        )}
+      />
+      {folded ? (
+        <div style={overlayContentStyle(metrics)}>{opener}</div>
+      ) : (
+        <div
+          role="group"
+          aria-label={label}
+          style={overlayContentStyle(metrics)}
+        >
+          {children}
+          {end}
+          {tools}
+          {info}
+          {opener}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/overlay/ui/OverlayBarStrip.tsx

@@ -0,0 +1,62 @@
+import type { ReactElement } from 'react';
+
+import { OverlayBarButton } from './OverlayBarButton.tsx';
+import type { OverlayBarShapeProps } from './overlayBarShape.ts';
+import {
+  OVERLAY_BAR_GROUND_STYLE,
+  overlayBarContentStyle,
+  overlayBarSideStyle,
+  overlayCardStyle,
+} from './overlayStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/**
+ * The bar that spans the width of the figure, its two ends pushed apart.
+ *
+ * It is in the flow above the picture rather than on it, and its ground is
+ * solid rather than translucent, because a strip reaching from one edge of the
+ * figure to the other is chrome the picture is mounted in — a floating card
+ * that wide would cover the very data it is there to explain.
+ *
+ * What folds when the figure is too narrow is the far end alone: the start
+ * holds the strip a reader moves between views with, and a reader who cannot
+ * leave the view they are on is stuck rather than merely short of options.
+ * @param props - See {@link OverlayBarShapeProps}.
+ * @returns The bar.
+ */
+export function OverlayBarStrip(props: OverlayBarShapeProps): ReactElement {
+  const { children, end, tools, info, more, placement, label } = props;
+  const { moreIcon, morePadded, folded, testId } = props;
+  const { metrics } = useOverlaySurface();
+
+  const opens = more !== undefined || (folded && end !== undefined);
+
+  return (
+    <div style={overlayCardStyle(placement, metrics)} data-testid={testId}>
+      <div style={OVERLAY_BAR_GROUND_STYLE} />
+      <div style={overlayBarContentStyle(metrics)}>
+        <div style={overlayBarSideStyle(metrics)}>{children}</div>
+        <div
+          role="group"
+          aria-label={label}
+          style={overlayBarSideStyle(metrics)}
+        >
+          {folded ? null : end}
+          {tools}
+          {info}
+          {opens ? (
+            <OverlayBarButton
+              placement={placement}
+              label={label}
+              icon={moreIcon}
+              padded={morePadded}
+            >
+              {folded ? end : null}
+              {more}
+            </OverlayBarButton>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/overlay/ui/OverlayCaption.tsx

@@ -0,0 +1,124 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+
+import { overlayCaptionStyle } from './overlayFigureStyles.ts';
+import { useOverlaySurface } from './overlaySurface.ts';
+
+/** What {@link OverlayCaption} says, and where. */
+export interface OverlayCaptionProps {
+  /**
+   * One sentence, in words the reader already has. It is the figure's own
+   * explanation, so it names what a mark is before it names what an axis is.
+   */
+  children: ReactNode;
+  /**
+   * Whether it floats over the figure or is laid out in the flow beneath it.
+   *
+   * A figure reserves the foot of its own box for the horizontal axis title, so
+   * a band floating there prints the sentence over the axis name. `below` is
+   * therefore what a standing explanation wants: it explains the picture rather
+   * than annotating a gesture, and nothing it says is worth covering the axis
+   * for. `over` is left for a sentence that has to reach the reader without the
+   * figure moving under their pointer.
+   * @default 'over'
+   */
+  placement?: 'over' | 'below';
+  /**
+   * Which edge it sits against, when it floats over the figure. A docked
+   * caption ignores it — it has only the one place to be.
+   * @default 'bottom'
+   */
+  edge?: 'top' | 'bottom';
+  /**
+   * How loud it is. `quiet` is the standing explanation; `strong` is live
+   * state the reader has just caused — `Adding to selection`, `31 samples
+   * selected`.
+   * @default 'quiet'
+   */
+  tone?: 'quiet' | 'strong';
+  /**
+   * Whether a screen reader is told about it as it changes. Turn it on for
+   * `strong`, so a selection made by keyboard is announced.
+   * @default false
+   */
+  live?: boolean;
+}
+
+/**
+ * The band across a figure that says, in one sentence, what it is showing.
+ *
+ * Floating, it is a gradient rather than a filled strip: the sentence stays
+ * readable while the marks under its far edge stay visible, so it never looks
+ * as though it has cropped the data. Docked, it needs neither — there is
+ * nothing under it to see through to.
+ * @param props - See {@link OverlayCaptionProps}.
+ * @returns The band.
+ */
+export function OverlayCaption(props: OverlayCaptionProps): ReactElement {
+  const { children, placement = 'over', edge = 'bottom' } = props;
+  const { tone = 'quiet', live = false } = props;
+  const { metrics } = useOverlaySurface();
+
+  return (
+    <div
+      style={placement === 'below' ? DOCKED_STYLE : bandStyle(edge, metrics)}
+    >
+      <span
+        style={overlayCaptionStyle(metrics, tone)}
+        aria-live={live ? 'polite' : undefined}
+        aria-atomic={live ? true : undefined}
+      >
+        {children}
+      </span>
+    </div>
+  );
+}
+
+/**
+ * The band is the one piece of chrome that spans the whole figure, so it keeps
+ * the pointer away from itself even though a card takes it back: a sentence
+ * across the foot of a scatter would otherwise swallow the start of every
+ * lasso drawn near the bottom edge.
+ * @param edge - Which edge the sentence sits against.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The band's rules.
+ */
+function bandStyle(
+  edge: 'top' | 'bottom',
+  metrics: OverlayMetrics,
+): CSSProperties {
+  return {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    top: edge === 'top' ? 0 : undefined,
+    bottom: edge === 'bottom' ? 0 : undefined,
+    display: 'flex',
+    alignItems: 'center',
+    padding: `${metrics.paddingY}px ${metrics.inset}px`,
+    background: `linear-gradient(to ${edge === 'bottom' ? 'top' : 'bottom'}, ${GROUND}, ${GROUND} 45%, ${CLEAR})`,
+    pointerEvents: 'none',
+  };
+}
+
+/**
+ * Nearly the page's own surface where the words are, and the same colour at
+ * zero strength where they stop. Fading to plain `transparent` interpolates
+ * through transparent black, which draws a grey bruise across the middle of a
+ * light figure.
+ */
+const GROUND = 'color-mix(in srgb, var(--surface) 86%, transparent)';
+const CLEAR = 'color-mix(in srgb, var(--surface) 0%, transparent)';
+
+/**
+ * A docked caption's own row: a block in the flow, with no ground of its own.
+ *
+ * It keeps the pointer, unlike the floating band. Below the figure there is no
+ * lasso to start underneath it, and a sentence a reader cannot select is a
+ * sentence they cannot quote.
+ */
+const DOCKED_STYLE = {
+  display: 'flex',
+  alignItems: 'center',
+} as const satisfies CSSProperties;