react-cheminfo 0.8.0 → 0.10.0

package/src/overlay/core/overlayPlacement.ts

@@ -0,0 +1,80 @@
+/** Which corner of a figure a floating card sits in. */
+export type OverlayCorner =
+  'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+/**
+ * Where a floating card sits: over one of the figure's corners, or docked
+ * outside the picture entirely.
+ *
+ * The three docked forms are the escape hatch for a figure whose data reaches
+ * all four corners. A chart that cannot spare a corner should move its
+ * controls out rather than cover the one cluster the reader came for.
+ *
+ * `stretch` is the one that spans the whole width rather than sitting at one
+ * end of the row: the settings bar of a figure embedded in somebody else's
+ * page, which is chrome above the picture and not a card floating on it. It is
+ * deliberately not offered as a floating placement — a full-width strip over a
+ * figure covers the very data it is there to explain.
+ */
+export type OverlayPlacement = OverlayCorner | 'above' | 'below' | 'stretch';
+
+/**
+ * The offsets a placement gives a card.
+ *
+ * Written out as a plain object of numbers rather than borrowed from React, so
+ * the whole of this entry point stays free of the framework that eventually
+ * spreads it onto a `style` prop. Only the two edges a corner is actually
+ * measured from are present: a key carrying `undefined` would still win over
+ * an offset the caller had merged in underneath it.
+ */
+export interface OverlayCornerStyle {
+  /** Whether the card is lifted out of the flow, or left in it and docked. */
+  position: 'absolute' | 'static';
+  /**
+   * Distance from the figure's top edge, in pixels.
+   * @default undefined — absent unless the card sits in a top corner
+   */
+  top?: number;
+  /**
+   * Distance from the figure's right edge, in pixels.
+   * @default undefined — absent unless the card sits in a right corner
+   */
+  right?: number;
+  /**
+   * Distance from the figure's bottom edge, in pixels.
+   * @default undefined — absent unless the card sits in a bottom corner
+   */
+  bottom?: number;
+  /**
+   * Distance from the figure's left edge, in pixels.
+   * @default undefined — absent unless the card sits in a left corner
+   */
+  left?: number;
+}
+
+/**
+ * The positioning a placement gives a card.
+ * @param placement - Where the card sits.
+ * @param inset - Distance kept between the card and the figure's edge, in pixels.
+ * @returns The style to spread onto the card. Every docked placement returns
+ * `position: 'static'`, so the same component lays out in the flow without a
+ * second code path.
+ */
+export function overlayCornerStyle(
+  placement: OverlayPlacement,
+  inset: number,
+): OverlayCornerStyle {
+  if (placement === 'top-left') {
+    return { position: 'absolute', top: inset, left: inset };
+  }
+  if (placement === 'top-right') {
+    return { position: 'absolute', top: inset, right: inset };
+  }
+  if (placement === 'bottom-left') {
+    return { position: 'absolute', bottom: inset, left: inset };
+  }
+  if (placement === 'bottom-right') {
+    return { position: 'absolute', bottom: inset, right: inset };
+  }
+  return { position: 'static' };
+}

package/src/overlay/core/overlayTierRoom.ts

@@ -0,0 +1,199 @@
+/**
+ * What a bar of controls is holding, and how much room each part of it needs.
+ *
+ * Every width here is an estimate of laid-out type rather than a measurement.
+ * Measuring the real labels would mean putting them in the document and
+ * reading their boxes back, which costs a layout pass on every render of every
+ * embedded figure on the page — and the answer would still arrive one frame
+ * after the width that prompted it. The estimate is deliberately generous: a
+ * bar that folds a word early costs the reader a caret, while one that folds
+ * late runs its controls off the edge of the figure.
+ *
+ * The geometry is restated here rather than read off the styles that draw it,
+ * because those styles are React's and this has to answer on a server, before
+ * anything exists to measure. Being an estimate is the point — it is allowed
+ * to be a few pixels out, and it is not allowed to need a browser.
+ */
+
+import type { OverlayMetrics } from './overlayMetrics.ts';
+
+/** One setting at the far end of a bar, for the room needed to write it. */
+export interface OverlayTierSetting {
+  /**
+   * The word written in front of the value where there is room — `Outlines`,
+   * `Colour`. It is the first thing dropped, because the name of a setting is
+   * read once and its value is read every time.
+   */
+  key: string;
+  /** What the setting currently reads: `Species`, `95%`. */
+  value: string;
+  /**
+   * Whether a row of the figure's own colours rides in front of the words.
+   * @default false
+   */
+  swatches?: boolean;
+}
+
+/** What a bar is holding, for the widths it needs to hold it. */
+export interface OverlayTierRoom {
+  /** What each tab reads. Empty for a figure with a single view. */
+  tabs: readonly string[];
+  /**
+   * The short form of each tab, in the same order — `Explains` for `How much
+   * each explains`. A tab with no short form keeps its long one, so shortening
+   * the two labels that are long does not blank the two that are not.
+   * @default the tabs themselves, which shortens nothing
+   */
+  shortTabs?: readonly string[];
+  /** The settings at the far end, in the order they are written. */
+  settings: readonly OverlayTierSetting[];
+  /**
+   * How many bare glyphs ride at the end: the `?` and the cog.
+   * @default 2
+   */
+  glyphs?: number;
+}
+
+/**
+ * The tab strip, sunken track and all.
+ * @param labels - What each tab reads.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The width in pixels; `0` where there is no strip at all.
+ */
+export function overlayStripWidth(
+  labels: readonly string[],
+  metrics: OverlayMetrics,
+): number {
+  if (labels.length === 0) return 0;
+  const segment = 2 * (metrics.paddingX + 2) + OVERLAY_TRACK_PADDING;
+  let total = OVERLAY_TRACK_PADDING * 2;
+  for (const label of labels) {
+    total += overlayTextWidth(label, metrics) + segment;
+  }
+  return total;
+}
+
+/**
+ * The settings, each written as a value button of its own.
+ * @param settings - What the bar holds at its far end.
+ * @param withKeys - Whether each value still carries its key word.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The width in pixels, the gaps between the buttons included.
+ */
+export function overlaySettingsWidth(
+  settings: readonly OverlayTierSetting[],
+  withKeys: boolean,
+  metrics: OverlayMetrics,
+): number {
+  let total = 0;
+  for (let index = 0; index < settings.length; index++) {
+    const setting = settings[index];
+    if (setting === undefined) continue;
+    const written = withKeys
+      ? `${setting.key} ${setting.value}`
+      : setting.value;
+    total += controlWidth(written, setting.swatches === true, metrics);
+    if (index > 0) total += metrics.gap;
+  }
+  return total;
+}
+
+/**
+ * Every setting gathered into one chip.
+ *
+ * What the chip saves is one button's worth of padding and one caret per
+ * setting it swallows — never the words themselves, which are the whole reason
+ * the reader is given a chip rather than a cog.
+ * @param settings - What the bar holds at its far end.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The width in pixels.
+ */
+export function overlayChipRoom(
+  settings: readonly OverlayTierSetting[],
+  metrics: OverlayMetrics,
+): number {
+  let written = '';
+  let swatches = false;
+  let separators = 0;
+  for (let index = 0; index < settings.length; index++) {
+    const setting = settings[index];
+    if (setting === undefined) continue;
+    written += setting.value;
+    if (setting.swatches === true) swatches = true;
+    if (index > 0) separators++;
+  }
+  return (
+    controlWidth(written, swatches, metrics) +
+    separators * OVERLAY_CHIP_SEPARATOR
+  );
+}
+
+/**
+ * The bare glyphs at the very end of the bar, with the bar's own padding.
+ *
+ * One extra gap is counted for the space between the two ends of the row,
+ * which is what a bar spanning the figure pushes its ends apart with.
+ * @param glyphs - How many bare glyphs ride at the end.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The width in pixels.
+ */
+export function overlayTailWidth(
+  glyphs: number,
+  metrics: OverlayMetrics,
+): number {
+  const count = Number.isFinite(glyphs) ? Math.max(0, Math.floor(glyphs)) : 0;
+  const buttons = count * (metrics.buttonSize + metrics.gap);
+  return buttons + 2 * metrics.paddingX + metrics.gap;
+}
+
+/**
+ * The room a run of words takes.
+ * @param text - The words.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The width in pixels.
+ */
+function overlayTextWidth(text: string, metrics: OverlayMetrics): number {
+  return text.length * metrics.fontSize * OVERLAY_CHARACTER_RATIO;
+}
+
+/**
+ * What one character of a label takes, as a fraction of the type size.
+ *
+ * A mixed-case interface sans averages a little over half its size per
+ * character. This sits above that average on purpose: the labels that decide a
+ * fold are the long ones, and a long label of wide letters is the case where
+ * being wrong runs the row off the figure rather than merely folding it early.
+ */
+const OVERLAY_CHARACTER_RATIO = 0.58;
+
+/** The band of sunken track showing around a segment, on every side. */
+const OVERLAY_TRACK_PADDING = 2;
+
+/** How many colours the swatch glyph draws before the last becomes a count. */
+const OVERLAY_SWATCH_DOTS = 4;
+
+/** What sits between two settings inside a chip, hairline and margins. */
+const OVERLAY_CHIP_SEPARATOR = 9;
+
+/**
+ * One button carrying words, a caret, and possibly a row of colours.
+ * @param written - The words on it.
+ * @param swatches - Whether the figure's colours ride in front of them.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The width in pixels, never under the button's own floor.
+ */
+function controlWidth(
+  written: string,
+  swatches: boolean,
+  metrics: OverlayMetrics,
+): number {
+  const dot = Math.max(4, Math.round(metrics.buttonSize / 6));
+  const glyph = swatches
+    ? OVERLAY_SWATCH_DOTS * dot + (OVERLAY_SWATCH_DOTS - 1) * 2 + 4
+    : 0;
+  const room = 2 * metrics.paddingX + metrics.fontSize;
+  return Math.max(
+    metrics.buttonSize,
+    overlayTextWidth(written, metrics) + glyph + room,
+  );
+}

package/src/overlay/core/overlayTiers.ts

@@ -0,0 +1,130 @@
+/**
+ * How much of itself a bar of controls writes, at the width it actually has.
+ *
+ * An embedded figure has no idea how wide the page around it is; it only knows
+ * its own box, which is why this answers from a measured component width and
+ * why there is no media query anywhere in the domain. A figure four hundred
+ * pixels wide in a wide page and the same figure filling a phone are the same
+ * problem, and a rule written against the viewport gets one of the two wrong.
+ *
+ * The ladder never *hides* a control. Each rung writes less of one: the key
+ * word in front of a value goes, then the long form of a tab label, then the
+ * settings gather into a single chip that still reads the configuration. That
+ * chip is the point of the whole ladder — a cog tells the reader nothing about
+ * how the figure is drawn, where `Species · 95%` answers the question they
+ * actually have without being opened at all.
+ */
+
+import type { OverlayMetrics } from './overlayMetrics.ts';
+import type { OverlayTierRoom } from './overlayTierRoom.ts';
+import {
+  overlayChipRoom,
+  overlaySettingsWidth,
+  overlayStripWidth,
+  overlayTailWidth,
+} from './overlayTierRoom.ts';
+
+/**
+ * How much of itself a bar writes.
+ *
+ * `full` writes every word. `condensed` drops the key word in front of each
+ * setting's value. `short` shortens the tab labels with it. `chip` gathers
+ * every setting into one chip that still reads the configuration. `tiny` keeps
+ * that chip and lets the tab strip scroll rather than shrink any further, so
+ * the strip is never clipped down to a row of initials.
+ */
+export type OverlayTier = 'full' | 'condensed' | 'short' | 'chip' | 'tiny';
+
+/** The width each rung of the ladder needs, in pixels. */
+export interface OverlayTierWidths {
+  /** Every word: full tab labels, and a key word in front of every value. */
+  full: number;
+  /** Full tab labels, values written without their key words. */
+  condensed: number;
+  /** Short tab labels, values written without their key words. */
+  short: number;
+  /** Short tab labels, every setting gathered into one chip. */
+  chip: number;
+}
+
+/**
+ * Which rung of the ladder a bar holding this content is on at this width.
+ *
+ * An unmeasured bar — a width of zero, which is what a component reports
+ * before its first layout and what a server render always reports — is given
+ * the roomiest tier. Folded is the answer that costs the reader something, so
+ * it is never the answer given on a guess; a bar that opened folded and sprang
+ * open a frame later would flicker on every page that embeds the figure.
+ * @param width - Width of the bar itself, in pixels, never of the page.
+ * @param room - See {@link OverlayTierRoom}.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The tier.
+ */
+export function overlayTier(
+  width: number,
+  room: OverlayTierRoom,
+  metrics: OverlayMetrics,
+): OverlayTier {
+  if (!Number.isFinite(width) || width <= 0) return 'full';
+  const widths = overlayTierWidths(room, metrics);
+  if (width >= widths.full) return 'full';
+  if (width >= widths.condensed) return 'condensed';
+  if (width >= widths.short) return 'short';
+  if (width >= widths.chip) return 'chip';
+  return 'tiny';
+}
+
+/**
+ * The width each rung needs, for this content at these measurements.
+ *
+ * Nothing here is a number a caller has to know: a viewer with two tabs stays
+ * roomy far longer than one with six, and a site that has translated the tab
+ * names has changed exactly these widths. That is why the content goes in and
+ * the thresholds come out, rather than the other way round.
+ *
+ * The rungs are forced to descend even where the writing saves nothing — a bar
+ * holding one setting has a chip exactly as wide as the value button it
+ * replaces — because a lower rung asking for more room than the rung above it
+ * would step the bar *down* into a tier that does not fit.
+ * @param room - See {@link OverlayTierRoom}.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns See {@link OverlayTierWidths}.
+ */
+export function overlayTierWidths(
+  room: OverlayTierRoom,
+  metrics: OverlayMetrics,
+): OverlayTierWidths {
+  const { tabs, shortTabs = tabs, settings, glyphs = 2 } = room;
+  const long = overlayStripWidth(tabs, metrics);
+  const brief = overlayStripWidth(shortened(tabs, shortTabs), metrics);
+  const tail = overlayTailWidth(glyphs, metrics);
+  const keyed = overlaySettingsWidth(settings, true, metrics);
+  const bare = overlaySettingsWidth(settings, false, metrics);
+
+  const full = long + keyed + tail;
+  const condensed = Math.min(full, long + bare + tail);
+  const short = Math.min(condensed, brief + bare + tail);
+  const chip = Math.min(
+    short,
+    brief + overlayChipRoom(settings, metrics) + tail,
+  );
+  return { full, condensed, short, chip };
+}
+
+/**
+ * The tab labels as they read once shortened.
+ * @param tabs - What each tab reads in full.
+ * @param shortTabs - The short forms, in the same order.
+ * @returns The labels to lay out.
+ */
+function shortened(
+  tabs: readonly string[],
+  shortTabs: readonly string[],
+): readonly string[] {
+  if (shortTabs === tabs) return tabs;
+  const labels: string[] = [];
+  for (let index = 0; index < tabs.length; index++) {
+    labels.push(shortTabs[index] ?? tabs[index] ?? '');
+  }
+  return labels;
+}

package/src/overlay/core/placeOverlayCard.ts

@@ -0,0 +1,93 @@
+/** What {@link placeOverlayCard} has to know. */
+export interface OverlayCardPlacementOptions {
+  /** Pointer position inside the figure, in pixels from its left. */
+  pointerX: number;
+  /** Pointer position inside the figure, in pixels from its top. */
+  pointerY: number;
+  /** Width of the card, as it was last measured. */
+  cardWidth: number;
+  /** Height of the card, as it was last measured. */
+  cardHeight: number;
+  /** Width of the box the card has to stay inside. */
+  boxWidth: number;
+  /** Height of that box. */
+  boxHeight: number;
+  /**
+   * Gap kept between the pointer and the card, so the card never covers the
+   * mark being read.
+   * @default 14
+   */
+  offset?: number;
+}
+
+/** Where a pointer-following card goes, and which way round it ended up. */
+export interface OverlayCardPlacement {
+  /** Distance from the box's left edge to the card's left edge. */
+  left: number;
+  /** Distance from the box's top edge to the card's top edge. */
+  top: number;
+  /** Whether the card had to open to the pointer's left. */
+  flippedX: boolean;
+  /** Whether it had to open above the pointer. */
+  flippedY: boolean;
+}
+
+/**
+ * Place a card down and to the right of the pointer, flipping it to the other
+ * side of whichever axis would push it out of the figure.
+ *
+ * Pure arithmetic on numbers the caller has already measured, so it runs on
+ * every pointer move without touching the DOM: reading the card's size back
+ * from the layout on each move would force a reflow every frame. Flipping
+ * rather than only clamping matters because a card clamped against the right
+ * edge sits under the pointer, and the mark the reader is pointing at is
+ * exactly the one it then hides.
+ * @param options - See {@link OverlayCardPlacementOptions}.
+ * @returns Where to put the card's top left corner.
+ */
+export function placeOverlayCard(
+  options: OverlayCardPlacementOptions,
+): OverlayCardPlacement {
+  const {
+    pointerX,
+    pointerY,
+    cardWidth,
+    cardHeight,
+    boxWidth,
+    boxHeight,
+    offset = DEFAULT_OFFSET,
+  } = options;
+
+  const flippedX = pointerX + offset + cardWidth > boxWidth;
+  const flippedY = pointerY + offset + cardHeight > boxHeight;
+  return {
+    left: withinBox(
+      flippedX ? pointerX - offset - cardWidth : pointerX + offset,
+      boxWidth - cardWidth,
+    ),
+    top: withinBox(
+      flippedY ? pointerY - offset - cardHeight : pointerY + offset,
+      boxHeight - cardHeight,
+    ),
+    flippedX,
+    flippedY,
+  };
+}
+
+const DEFAULT_OFFSET = 14;
+
+/**
+ * The flip alone is not enough when the card is larger than the figure it has
+ * to live in — a fifty pixel sparkline with a full readout beside it — because
+ * both sides then overflow. Clamping the far edge to zero keeps the card's top
+ * left corner on screen, which is where the reader's eye already is, instead of
+ * pushing the whole card past the edge and showing nothing at all.
+ * @param value - The offset the flip arrived at.
+ * @param furthest - The largest offset that still leaves the card inside.
+ * @returns The offset, brought back between zero and that limit.
+ */
+function withinBox(value: number, furthest: number): number {
+  if (!Number.isFinite(value)) return 0;
+  const limit = Number.isFinite(furthest) ? Math.max(0, furthest) : 0;
+  return Math.max(0, Math.min(value, limit));
+}

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>
+  );
+}