react-cheminfo 0.9.0 → 0.10.0

package/src/overlay/ui/index.ts

@@ -0,0 +1,72 @@
+/**
+ * The chrome that floats over a figure: a small card of controls, the plain
+ * sentence under it, the key naming what its colours mean, and the card that
+ * follows the pointer.
+ *
+ * It is a domain of its own rather than part of any chart, because a scatter,
+ * a spectrum and a map all want the same card in the same corner, and because
+ * the rules for one are the reason two figures in this package look like they
+ * belong to the same tool.
+ */
+
+export type { OverlayActionProps } from './OverlayAction.tsx';
+export { OverlayAction } from './OverlayAction.tsx';
+export type { OverlayBarProps } from './OverlayBar.tsx';
+export { OverlayBar } from './OverlayBar.tsx';
+export type { OverlayCaptionProps } from './OverlayCaption.tsx';
+export { OverlayCaption } from './OverlayCaption.tsx';
+export type { OverlayChipProps, OverlayChipSetting } from './OverlayChip.tsx';
+export { OverlayChip } from './OverlayChip.tsx';
+export { OverlayDivider } from './OverlayDivider.tsx';
+export type { OverlayGroupProps } from './OverlayGroup.tsx';
+export { OverlayGroup } from './OverlayGroup.tsx';
+export type { OverlayInfoProps } from './OverlayInfo.tsx';
+export { OverlayInfo } from './OverlayInfo.tsx';
+export type { OverlayLayerProps } from './OverlayLayer.tsx';
+export { OverlayLayer } from './OverlayLayer.tsx';
+export type {
+  OverlayLegendEntry,
+  OverlayLegendProps,
+} from './OverlayLegend.tsx';
+export { OverlayLegend } from './OverlayLegend.tsx';
+export type { OverlayLegendMarkProps } from './OverlayLegendMark.tsx';
+export { OverlayLegendMark } from './OverlayLegendMark.tsx';
+export type { OverlayNumberProps } from './OverlayNumber.tsx';
+export { OverlayNumber } from './OverlayNumber.tsx';
+export type { OverlayPanelProps } from './OverlayPanel.tsx';
+export { OverlayPanel } from './OverlayPanel.tsx';
+export type { OverlayPillOption, OverlayPillsProps } from './OverlayPills.tsx';
+export { OverlayPills } from './OverlayPills.tsx';
+export type { OverlaySegmentedSize } from './overlayPillStyles.ts';
+export type {
+  OverlayReadoutProps,
+  OverlayReadoutRow,
+} from './OverlayReadout.tsx';
+export { OverlayReadout } from './OverlayReadout.tsx';
+export type {
+  OverlayControlProps,
+  OverlayOption,
+  OverlayRowLayout,
+  OverlayRowProps,
+} from './OverlayRow.tsx';
+export { OverlayRow } from './OverlayRow.tsx';
+export type { OverlaySegmentedProps } from './OverlaySegmented.tsx';
+export { OverlaySegmented } from './OverlaySegmented.tsx';
+export type {
+  OverlaySelectAppearance,
+  OverlaySelectProps,
+} from './OverlaySelect.tsx';
+export { OverlaySelect } from './OverlaySelect.tsx';
+export type { OverlaySwatchIconProps } from './OverlaySwatchIcon.tsx';
+export { OverlaySwatchIcon } from './OverlaySwatchIcon.tsx';
+export type {
+  OverlayToggleAppearance,
+  OverlayToggleProps,
+} from './OverlayToggle.tsx';
+export { OverlayToggle } from './OverlayToggle.tsx';
+export type { OverlayValueButtonProps } from './OverlayValueButton.tsx';
+export { OverlayValueButton } from './OverlayValueButton.tsx';
+export type { OverlayValueMenuProps } from './OverlayValueMenu.tsx';
+export { OverlayValueMenu } from './OverlayValueMenu.tsx';
+export type { OverlaySurface } from './overlaySurface.ts';
+export { useCoarsePointer, useOverlaySurface } from './overlaySurface.ts';

package/src/overlay/ui/overlayBarShape.ts

@@ -0,0 +1,113 @@
+/**
+ * Whether a bar of controls is folded, and what either shape of it is handed.
+ *
+ * A bar has two shapes that share almost everything and agree on nothing about
+ * how they sit — a card floating in a corner of the figure, and a strip
+ * spanning the width above it — so what they have in common is written here
+ * once and each of them is left free to lay itself out.
+ */
+
+import type { IconName } from '@blueprintjs/core';
+import type { ReactNode } from 'react';
+import { useEffect, useRef } from 'react';
+
+import { shouldCollapseOverlay } from '../core/overlayCollapse.ts';
+import type { OverlayPlacement } from '../core/overlayPlacement.ts';
+
+/** What both shapes of a bar are drawn from, with every default resolved. */
+export interface OverlayBarShapeProps {
+  /** The controls at the start of the row. */
+  children: ReactNode;
+  /**
+   * What sits at the far end of the row.
+   * @default undefined — the end holds only the glyphs
+   */
+  end?: ReactNode;
+  /**
+   * The glyph-sized tools that act on the figure rather than change it.
+   * @default undefined — the bar carries no tools
+   */
+  tools?: ReactNode;
+  /**
+   * The one control that never folds.
+   * @default undefined — the bar carries no glyph
+   */
+  info?: ReactNode;
+  /**
+   * What waits behind the button.
+   * @default undefined — nothing but whatever has folded away
+   */
+  more?: ReactNode;
+  /** Where the bar sits. */
+  placement: OverlayPlacement;
+  /** What the group of controls is called. */
+  label: string;
+  /** Glyph of the button that opens the rest. */
+  moreIcon: IconName;
+  /** Whether that button's panel is drawn with the card's own padding. */
+  morePadded: boolean;
+  /** Whether the bar has folded its controls away behind that button. */
+  folded: boolean;
+  /**
+   * Value of the `data-testid` attribute of the bar.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/** What decides whether a bar is folded. */
+export interface OverlayBarFoldOptions {
+  /** What the caller asked for, when it is holding the fold itself. */
+  collapsed: boolean | undefined;
+  /** Whether the bar was asked to start folded. */
+  startedFolded: boolean;
+  /** Width of the figure, in pixels; `0` before it has been measured. */
+  width: number;
+  /** The width under which the bar folds on its own. */
+  collapseBelow: number;
+}
+
+/**
+ * Whether the bar is folded.
+ *
+ * A caller holding `collapsed` is obeyed outright, so a bar driven from
+ * outside never argues with the figure's width; every other bar folds itself
+ * once the figure is too narrow, or because it was asked to start that way.
+ * @param options - See {@link OverlayBarFoldOptions}.
+ * @returns Whether it is folded.
+ */
+export function overlayBarFolded(options: OverlayBarFoldOptions): boolean {
+  const { collapsed, startedFolded, width, collapseBelow } = options;
+  return (
+    collapsed ?? (startedFolded || shouldCollapseOverlay(width, collapseBelow))
+  );
+}
+
+/**
+ * Tell the caller the bar folded itself.
+ *
+ * A caller holding `collapsed` already knows what it asked for; what it cannot
+ * see is the figure crossing the breakpoint under a bar left to decide, so
+ * that is the only thing reported. Whom to tell is read through a ref, so an
+ * inline arrow may be passed on every render without the report firing again
+ * for a fold that has not changed.
+ * @param folded - Whether the bar is folded now.
+ * @param onCollapsedChange - Who to tell, when there is anybody to tell.
+ */
+export function useFoldReport(
+  folded: boolean,
+  onCollapsedChange: ((collapsed: boolean) => void) | undefined,
+): void {
+  const tell = useRef(onCollapsedChange);
+  const told = useRef(folded);
+
+  useEffect(() => {
+    tell.current = onCollapsedChange;
+  });
+
+  useEffect(() => {
+    if (told.current === folded) return;
+    told.current = folded;
+    tell.current?.(folded);
+  }, [folded]);
+}

package/src/overlay/ui/overlayControlStyles.ts

@@ -0,0 +1,176 @@
+/**
+ * The rules one control inside a floating card is drawn with.
+ *
+ * They are apart from the card's own rules because a control is the part a
+ * future chart will reuse without the card: a legend swatch, a glyph standing
+ * for one setting, a titled cluster in a settings panel. Every one of them
+ * takes the card's measurements, so a control looks the same wherever it is
+ * put.
+ */
+
+import type { CSSProperties } from 'react';
+
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+
+/**
+ * The hairline between two clusters of controls.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The divider's rules.
+ */
+export function overlayDividerStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    width: 1,
+    alignSelf: 'stretch',
+    minHeight: metrics.controlHeight - 8,
+    background: 'var(--border)',
+    margin: `0 ${Math.max(2, metrics.gap - 4)}px`,
+  };
+}
+
+/**
+ * The square in front of a toggle's caption.
+ *
+ * This is the one rule here that draws a colour it was handed rather than a
+ * family token: given a series' own colour, a row of toggles becomes the
+ * figure's legend, and a swatch that did not match the mark on the chart would
+ * be worse than no swatch at all. The inset hairline is what keeps a pale
+ * series visible against the card.
+ * @param color - The colour the swatch stands for.
+ * @returns The swatch's rules.
+ */
+export function overlaySwatchStyle(color: string): CSSProperties {
+  return {
+    display: 'inline-block',
+    width: 10,
+    height: 10,
+    borderRadius: 2,
+    background: color,
+    boxShadow: 'inset 0 0 0 1px var(--border)',
+  };
+}
+
+/**
+ * A cluster of controls that answer one question together.
+ *
+ * It never wraps inside itself, so a cluster moves to the next line of the
+ * card whole rather than breaking across two lines mid-thought.
+ * @param metrics - The measurements the card is drawn from.
+ * @param direction - Whether the controls sit side by side or stacked.
+ * @returns The cluster's rules.
+ */
+export function overlayGroupStyle(
+  metrics: OverlayMetrics,
+  direction: 'row' | 'column',
+): CSSProperties {
+  return {
+    display: 'inline-flex',
+    flexDirection: direction,
+    flexWrap: 'nowrap',
+    alignItems: direction === 'row' ? 'center' : 'flex-start',
+    gap: metrics.gap,
+  };
+}
+
+/**
+ * The title over a cluster of controls.
+ *
+ * Small capitals rather than a heavier weight: the title has to read as a
+ * label *on* the cluster, and anything that looks like the captions inside it
+ * is taken for one more control.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The title's rules.
+ */
+export function overlayGroupTitleStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: 4,
+    color: 'var(--text-faint)',
+    fontSize: Math.max(9, metrics.labelSize - 2),
+    fontWeight: 600,
+    letterSpacing: '0.06em',
+    textTransform: 'uppercase',
+    whiteSpace: 'nowrap',
+  };
+}
+
+/** How an icon button stands. */
+export interface OverlayIconLook {
+  /**
+   * Whether the pointer is over it or the keyboard is on it.
+   * @default false
+   */
+  hovered?: boolean;
+  /**
+   * 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;
+}
+
+/**
+ * A setting reduced to its glyph.
+ *
+ * It carries no outline and no ground until it is pointed at, because a bar of
+ * six settings each in its own box is six boxes competing with the figure
+ * underneath, and the reader is looking for a setting rather than for a
+ * button. What answers for the missing box is the ink: faint at rest, the
+ * caption's grey under the pointer, full strength while the choices are open,
+ * so the button tells the reader what it is doing without ever growing an edge.
+ * @param metrics - The measurements the card is drawn from.
+ * @param look - See {@link OverlayIconLook}.
+ * @returns The button's rules.
+ */
+export function overlayIconButtonStyle(
+  metrics: OverlayMetrics,
+  look: OverlayIconLook,
+): CSSProperties {
+  const { hovered = false, active = false, disabled = false } = look;
+  const lit = !disabled && (hovered || active);
+  return {
+    boxSizing: 'border-box',
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: 2,
+    minWidth: metrics.buttonSize,
+    height: metrics.buttonSize,
+    padding: `0 ${OVERLAY_ICON_PADDING}px`,
+    border: 'none',
+    borderRadius: metrics.controlRadius + 1,
+    background: lit ? 'var(--surface-sunken)' : 'transparent',
+    color: iconInk(active && !disabled, lit),
+    font: 'inherit',
+    fontSize: metrics.fontSize,
+    lineHeight: 1,
+    whiteSpace: 'nowrap',
+    cursor: disabled ? 'default' : 'pointer',
+    opacity: disabled ? 0.6 : 1,
+  };
+}
+
+/**
+ * The room each side of a glyph.
+ *
+ * Two pixels, which is what lets a palette of four dots sit in a button that
+ * is otherwise square: the button keeps its width as a floor rather than as a
+ * size, so the one control whose glyph is wider than it is tall grows instead
+ * of cropping the dots that are the whole point of it.
+ */
+const OVERLAY_ICON_PADDING = 2;
+
+/**
+ * What an icon button is drawn in.
+ * @param active - Whether its choices are showing.
+ * @param lit - Whether it is pointed at or active.
+ * @returns The ink.
+ */
+function iconInk(active: boolean, lit: boolean): string {
+  if (active) return 'var(--text)';
+  return lit ? 'var(--text-muted)' : 'var(--text-faint)';
+}

package/src/overlay/ui/overlayFigureStyles.ts

@@ -0,0 +1,111 @@
+/**
+ * The rules the chrome that explains a figure is drawn with: the plain-English
+ * band under it, the key naming what its colours mean, and the card that
+ * follows the pointer.
+ *
+ * This is the half of the domain that answers "what am I looking at", and it
+ * is separated from the controls because a figure can need all of it while
+ * offering nothing to change.
+ */
+
+import type { CSSProperties } from 'react';
+
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+
+/**
+ * The plain-English band under a figure.
+ *
+ * `strong` is for a sentence the reader is meant to act on — what a drag is
+ * about to do — and is the one place the chrome raises its voice.
+ * @param metrics - The measurements the card is drawn from.
+ * @param tone - How loudly it speaks.
+ * @returns The caption band's rules.
+ */
+export function overlayCaptionStyle(
+  metrics: OverlayMetrics,
+  tone: 'quiet' | 'strong',
+): CSSProperties {
+  return {
+    display: 'block',
+    maxWidth: '100%',
+    padding: `${metrics.paddingY}px ${metrics.paddingX}px`,
+    color: tone === 'strong' ? 'var(--text)' : 'var(--text-muted)',
+    fontSize: metrics.labelSize,
+    fontWeight: tone === 'strong' ? 600 : 400,
+    lineHeight: 1.35,
+    textWrap: 'pretty',
+  };
+}
+
+/**
+ * The stack of entries naming what a colour or a shape means.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The legend's rules.
+ */
+export function overlayLegendStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    position: 'relative',
+    display: 'flex',
+    flexDirection: 'column',
+    gap: Math.max(2, metrics.gap - 4),
+    padding: `${metrics.paddingY}px ${metrics.paddingX}px`,
+    color: 'var(--text)',
+    fontSize: metrics.labelSize,
+    lineHeight: 1.3,
+  };
+}
+
+/**
+ * The sentence over a legend's entries, which names the encoding.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The title's rules.
+ */
+export function overlayLegendTitleStyle(
+  metrics: OverlayMetrics,
+): CSSProperties {
+  return {
+    marginBottom: 2,
+    color: 'var(--text-muted)',
+    fontSize: metrics.labelSize,
+    fontWeight: 600,
+    whiteSpace: 'nowrap',
+  };
+}
+
+/** One entry of a legend: its mark, then what the mark means. */
+export const OVERLAY_LEGEND_ENTRY_STYLE = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 6,
+  border: 'none',
+  background: 'none',
+  color: 'inherit',
+  font: 'inherit',
+  padding: 0,
+  textAlign: 'left',
+} as const satisfies CSSProperties;
+
+/**
+ * The card that follows the pointer, holding everything known about one point.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The readout's rules.
+ */
+export function overlayReadoutStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    position: 'absolute',
+    zIndex: 2,
+    display: 'flex',
+    flexDirection: 'column',
+    gap: 2,
+    maxWidth: 280,
+    padding: `${metrics.paddingY}px ${metrics.paddingX}px`,
+    borderRadius: 'var(--radius)',
+    border: '1px solid var(--border)',
+    background: 'var(--surface)',
+    boxShadow: 'var(--shadow-md)',
+    color: 'var(--text)',
+    fontSize: metrics.labelSize,
+    lineHeight: 1.35,
+    pointerEvents: 'none',
+  };
+}

package/src/overlay/ui/overlayPanelContext.ts

@@ -0,0 +1,42 @@
+/**
+ * What the rows of one settings panel agree on.
+ *
+ * A panel is handed its controls as opaque children, so it cannot reach into
+ * them and set a prop; and every row deciding for itself whether it is a line
+ * on a bar or a cell in a grid is exactly how a panel ends up with three row
+ * shapes in it. So the panel says once, here, that its rows are cells and how
+ * wide the name column is, and every row reads it back.
+ */
+
+import { createContext, useContext } from 'react';
+
+/** What every row inside an {@link OverlayPanel} reads from it. */
+export interface OverlayPanelShape {
+  /**
+   * Width of the name column, in pixels. Settled by the panel rather than by
+   * each row, because a column whose width is decided per row is not a column.
+   */
+  nameWidth: number;
+}
+
+/**
+ * The panel a control is sitting in, if it is sitting in one.
+ *
+ * A control rendered on a bar, or on its own, gets `undefined` — which is what
+ * leaves every existing caller of {@link OverlayRow} laid out as the line it
+ * has always been.
+ * @returns The panel, or `undefined` outside one.
+ */
+export function useOverlayPanelShape(): OverlayPanelShape | undefined {
+  return useContext(OverlayPanelContext);
+}
+
+/**
+ * The shape an {@link OverlayPanel} hands down to the controls inside it.
+ *
+ * Published for the panel alone. A control reaches it through
+ * {@link useOverlayPanelShape}.
+ */
+export const OverlayPanelContext = createContext<OverlayPanelShape | undefined>(
+  undefined,
+);