react-cheminfo 0.8.0 → 0.10.0

package/src/chart/ui/chartStyles.ts

@@ -0,0 +1,194 @@
+/**
+ * Every rule the frame and its axes are drawn with.
+ *
+ * A frame is the one part of a figure the reader is not meant to notice, so
+ * the whole domain's visual decision fits in this file: three weights of line
+ * and one colour of text. Grid rules take the faintest border token, the rule
+ * at zero takes the strong one held back, and the axis line takes it outright
+ * — a ramp the eye reads as depth rather than as three unrelated greys.
+ *
+ * The room numbers live here too. They are what makes a chart with no titles
+ * give its plot back the forty pixels it was reserving for words nobody asked
+ * for, and keeping them beside the type sizes is what keeps the two in step.
+ */
+
+import type { CSSProperties } from 'react';
+
+import type { ChartAxisScale } from '../core/chartAxisScale.ts';
+
+import type {
+  ChartAxisSpec,
+  ChartMargins,
+  ChartPlotArea,
+} from './ChartFrame.tsx';
+
+/** Room kept around the plot before either axis asks for any of its own. */
+export const CHART_BASE_MARGINS = {
+  top: 10,
+  right: 12,
+  bottom: 8,
+  left: 10,
+} as const;
+
+/** Room a set of tick marks and their labels needs, outside the plot. */
+export const CHART_TICK_ROOM = { bottom: 22, left: 32 } as const;
+
+/** Room an axis title needs, beyond whatever its ticks already took. */
+export const CHART_TITLE_ROOM = { bottom: 18, left: 16 } as const;
+
+/** How far a tick mark reaches out of the plot, in pixels. */
+export const CHART_TICK_LENGTH = 4;
+
+/** Baseline of a horizontal tick label, below the bottom of the plot. */
+export const CHART_TICK_LABEL_OFFSET = 15;
+
+/** How far a vertical tick label ends before the left of the plot. */
+export const CHART_TICK_LABEL_INSET = 8;
+
+/** Baseline of an axis title, past the room its ticks took. */
+export const CHART_TITLE_OFFSET = 13;
+
+/**
+ * How much room one edge of the plot gives up.
+ *
+ * An inner cell of a pair grid keeps its grid and drops its ticks, and a
+ * figure that names its axes in a caption drops its titles; both get the
+ * pixels back rather than framing the plot with empty margin. An axis whose
+ * labels were divided by a power of ten always keeps its title room even
+ * unnamed, because without the factor written down the labels read as the
+ * wrong number entirely.
+ * @param side - Which edge, since a column of numbers is wider than a row.
+ * @param spec - How the axis on that edge was asked for.
+ * @param scale - The axis as it was niced, for the power of ten it lifted.
+ * @returns The margin, in pixels.
+ */
+export function chartOuterRoom(
+  side: 'bottom' | 'left',
+  spec: ChartAxisSpec,
+  scale: ChartAxisScale,
+): number {
+  const { label, showTicks = true } = spec;
+  const named = (label !== undefined && label !== '') || scale.exponent !== 0;
+  const ticks = showTicks ? CHART_TICK_ROOM[side] : 0;
+  return (
+    CHART_BASE_MARGINS[side] + ticks + (named ? CHART_TITLE_ROOM[side] : 0)
+  );
+}
+
+/**
+ * The rectangle the data is drawn in.
+ *
+ * Both sides are clamped rather than trusted. A chart in a collapsed panel is
+ * measured at nothing before it is measured properly, and a plot of minus
+ * eighty pixels would reach the DOM as an invalid `rect` and take the figure
+ * down with it.
+ * @param width - Total width of the figure, in pixels.
+ * @param height - Total height.
+ * @param margins - What the caller insists on, over the rest.
+ * @param outer - What the two written edges asked for, from
+ * {@link chartOuterRoom}.
+ * @param outer.bottom - Room the horizontal axis asked for below the plot.
+ * @param outer.left - Room the vertical axis asked for beside it.
+ * @returns The plot rectangle.
+ */
+export function chartPlotArea(
+  width: number,
+  height: number,
+  margins: Partial<ChartMargins>,
+  outer: { bottom: number; left: number },
+): ChartPlotArea {
+  const top = margins.top ?? CHART_BASE_MARGINS.top;
+  const right = margins.right ?? CHART_BASE_MARGINS.right;
+  const left = margins.left ?? outer.left;
+  const plotWidth = Math.max(0, width - left - right);
+  const plotHeight = Math.max(
+    0,
+    height - top - (margins.bottom ?? outer.bottom),
+  );
+  return {
+    left,
+    top,
+    right: left + plotWidth,
+    bottom: top + plotHeight,
+    width: plotWidth,
+    height: plotHeight,
+  };
+}
+
+/**
+ * The block a figure occupies, which the floating chrome is positioned
+ * against.
+ * @param width - Total width, in pixels.
+ * @param height - Total height.
+ * @returns The wrapper's rules.
+ */
+export function chartFrameStyle(width: number, height: number): CSSProperties {
+  return {
+    position: 'relative',
+    width: Math.max(0, width),
+    height: Math.max(0, height),
+  };
+}
+
+/**
+ * The drawing surface, which fills the block exactly.
+ *
+ * It paints outside its own box on purpose: an axis title sitting on the last
+ * pixel of the margin would otherwise lose its descenders to the viewport
+ * edge, and a clipped `y` is a typographic bug nobody can explain.
+ */
+export const CHART_SVG_STYLE = {
+  display: 'block',
+  overflow: 'visible',
+} as const satisfies CSSProperties;
+
+/** A rule across the plot at one tick, drawn under everything. */
+export const CHART_GRID_STYLE = {
+  stroke: 'var(--border)',
+  strokeWidth: 1,
+  shapeRendering: 'crispEdges',
+} as const satisfies CSSProperties;
+
+/**
+ * The rule at zero, which is what separates a positive loading from a
+ * negative one at a glance and so outweighs the grid without becoming an axis.
+ */
+export const CHART_ZERO_RULE_STYLE = {
+  stroke: 'var(--border-strong)',
+  strokeWidth: 1,
+  strokeOpacity: 0.6,
+  shapeRendering: 'crispEdges',
+} as const satisfies CSSProperties;
+
+/** The line along the edge the axis is written on. */
+export const CHART_AXIS_LINE_STYLE = {
+  stroke: 'var(--border-strong)',
+  strokeWidth: 1,
+  shapeRendering: 'crispEdges',
+} as const satisfies CSSProperties;
+
+/** The stub outside the plot that ties a label to its value. */
+export const CHART_TICK_MARK_STYLE = {
+  stroke: 'var(--border-strong)',
+  strokeWidth: 1,
+  shapeRendering: 'crispEdges',
+} as const satisfies CSSProperties;
+
+/**
+ * One tick written out. The figures are tabular so that a column of them on a
+ * vertical axis lines up on the decimal point instead of wandering.
+ */
+export const CHART_TICK_LABEL_STYLE = {
+  fill: 'var(--text-muted)',
+  fontSize: 11,
+  fontVariantNumeric: 'tabular-nums',
+  userSelect: 'none',
+} as const satisfies CSSProperties;
+
+/** What the axis measures, and any power of ten its labels were divided by. */
+export const CHART_AXIS_TITLE_STYLE = {
+  fill: 'var(--text-muted)',
+  fontSize: 12,
+  fontWeight: 500,
+  userSelect: 'none',
+} as const satisfies CSSProperties;

package/src/chart/ui/index.ts

@@ -0,0 +1,34 @@
+/**
+ * The SVG frame a figure is drawn in, and the two charts that report what the
+ * pointer is over: a band chart for measurements on a grid, a stick chart for
+ * a list of peaks picked off one.
+ */
+
+export type { ChartAxisProps } from './ChartAxis.tsx';
+export type { WheelZoomApi, WheelZoomOptions } from './useWheelZoom.ts';
+export { CHART_WHEEL_DWELL, useWheelZoom } from './useWheelZoom.ts';
+export { ChartAxis } from './ChartAxis.tsx';
+export type {
+  ChartAxisSpec,
+  ChartFrameProps,
+  ChartFrameRender,
+  ChartMargins,
+  ChartPlotArea,
+} from './ChartFrame.tsx';
+export { ChartFrame } from './ChartFrame.tsx';
+export type { ChartSeriesMarksProps } from './ChartSeriesMarks.tsx';
+export { ChartSeriesMarks } from './ChartSeriesMarks.tsx';
+export type { ChartTrackingLayerProps } from './ChartTrackingLayer.tsx';
+export { ChartTrackingLayer } from './ChartTrackingLayer.tsx';
+export type {
+  ChartSeries,
+  ChartSeriesKind,
+  ChartTrackEvent,
+  TrackedLineChartProps,
+} from './TrackedLineChart.tsx';
+export { TrackedLineChart } from './TrackedLineChart.tsx';
+export type {
+  ChartStickSeries,
+  TrackedStickChartProps,
+} from './TrackedStickChart.tsx';
+export { TrackedStickChart } from './TrackedStickChart.tsx';

package/src/chart/ui/stickChartModel.ts

@@ -0,0 +1,201 @@
+/**
+ * The arithmetic behind a stick chart, worked out before React sees it: the
+ * one path a series becomes, the stretch of axis its peaks cover, and which
+ * peak a place on that axis is asking about.
+ *
+ * It is here rather than in the component because none of it is a component:
+ * a peak list is a pair of arrays and a scale, and every question asked of it
+ * can be answered, and tested, without a renderer.
+ */
+
+import {
+  EMPTY_EXTENT,
+  chartPadExtent,
+  chartValuesExtent,
+} from '../core/chartExtent.ts';
+import type { ChartScale } from '../core/chartScale.ts';
+
+/** One set of sticks. */
+export interface ChartStickSeries {
+  /** A stable id, used as the React key and named in the tracking callback. */
+  id: string;
+  /** What the legend calls it, e.g. `PC 1`. */
+  label: string;
+  /** Where each stick ends, one value per measurement. */
+  values: ArrayLike<number>;
+  /**
+   * Where each stick starts. Without it a stick stands on the zero rule, which
+   * is what a loading is read from; with it the stick is the span between the
+   * two, which is how far along a component a measurement is pushed.
+   * @default undefined — every stick stands on zero
+   */
+  from?: ArrayLike<number>;
+  /** Its colour, normally from `chartSeriesColor`. */
+  color: string;
+  /**
+   * Whether it is drawn at all — what a legend entry switches.
+   * @default true
+   */
+  visible?: boolean;
+  /**
+   * Whether it is drawn faintly behind the rest, which is what the average
+   * sample is in a loadings panel.
+   * @default false
+   */
+  muted?: boolean;
+}
+/** What the geometry needs of a drawn frame: the two scales and the rectangle. */
+export interface StickFrame {
+  /** The rectangle to draw in. */
+  plot: { top: number; bottom: number; left: number; right: number };
+  /** Data to pixels, horizontally. */
+  x: ChartScale;
+  /** Data to pixels, vertically; its `factor` is negative. */
+  y: ChartScale;
+}
+
+/**
+ * One path holding every stick of a series.
+ * @param item - The series.
+ * @param positions - Where each measurement sits.
+ * @param frame - The rectangle and the two scales.
+ * @returns The `d` attribute, empty when nothing was finite.
+ */
+export function stickPath(
+  item: ChartStickSeries,
+  positions: readonly number[],
+  frame: StickFrame,
+): string {
+  const { x, y } = frame;
+  const foot = zeroAt(frame);
+  let path = '';
+  for (let index = 0; index < positions.length; index++) {
+    const at = positions[index];
+    const value = item.values[index];
+    if (at === undefined || value === undefined || !Number.isFinite(value)) {
+      continue;
+    }
+    const pixelX = round(x.offset + at * x.factor);
+    const top = round(y.offset + value * y.factor);
+    const start = item.from === undefined ? foot : startOf(item, index, y);
+    if (start === null || !Number.isFinite(top)) continue;
+    path += `M${pixelX} ${start}V${top}`;
+  }
+  return path;
+}
+
+/**
+ * Where a stick starts when the series says so.
+ * @param item - The series.
+ * @param index - Which measurement.
+ * @param y - Data to pixels, vertically.
+ * @returns The pixel, or `null` when the value is not a number.
+ */
+function startOf(
+  item: ChartStickSeries,
+  index: number,
+  y: ChartScale,
+): number | null {
+  const value = item.from?.[index];
+  if (value === undefined || !Number.isFinite(value)) return null;
+  return round(y.offset + value * y.factor);
+}
+
+/**
+ * Where zero sits, which is what a stick stands on.
+ *
+ * The frame rules the plot at zero itself whenever the domain crosses it, so
+ * this only says where a stick's foot goes and never draws anything.
+ * @param frame - The rectangle and the two scales.
+ * @returns The pixel, clamped into the plot so a domain above zero still has a
+ * foot to stand on.
+ */
+export function zeroAt(frame: StickFrame): number {
+  const { plot, y } = frame;
+  const at = y.offset;
+  if (!Number.isFinite(at)) return plot.bottom;
+  return round(Math.min(plot.bottom, Math.max(plot.top, at)));
+}
+
+/**
+ * The measurement nearest a value on the axis.
+ * @param positions - Where each measurement sits, in order.
+ * @param value - Where the pointer is, in the axis' own units.
+ * @returns Its index, or -1 when there are none.
+ */
+export function nearestPosition(
+  positions: readonly number[],
+  value: number,
+): number {
+  const count = positions.length;
+  if (count === 0 || !Number.isFinite(value)) return -1;
+  let low = 0;
+  let high = count - 1;
+  while (low < high) {
+    const middle = (low + high) >> 1;
+    if ((positions[middle] as number) < value) {
+      low = middle + 1;
+    } else {
+      high = middle;
+    }
+  }
+  const here = positions[low] as number;
+  const previous = positions[low - 1];
+  if (previous === undefined) return low;
+  return Math.abs(previous - value) <= Math.abs(here - value) ? low - 1 : low;
+}
+
+/**
+ * The stretch of the axis the peaks cover.
+ * @param positions - Where each measurement sits.
+ * @returns The domain, padded so an edge peak is not drawn on the frame.
+ */
+export function spanOf(
+  positions: readonly number[],
+): readonly [number, number] {
+  const { min, max } = chartValuesExtent(positions);
+  if (min > max) return [0, 1];
+  // Not padded. The frame widens the domain to whole tick steps, which already
+  // leaves an edge peak off the frame, and a pad on top of that can push the
+  // lowest peak below a step — 206 padded to 199 nices to 0 rather than to
+  // 200, and a fifth of the width goes to masses the run never measured.
+  return min === max ? [min - 1, max + 1] : [min, max];
+}
+
+/**
+ * The vertical stretch the sticks need, zero among it.
+ * @param drawn - The visible series.
+ * @param count - How many measurements there are.
+ * @returns The domain.
+ */
+export function seriesDomain(
+  drawn: readonly ChartStickSeries[],
+  count: number,
+): readonly [number, number] {
+  let extent = EMPTY_EXTENT;
+  for (const item of drawn) {
+    extent = chartValuesExtent(item.values, { limit: count, into: extent });
+    if (item.from !== undefined) {
+      extent = chartValuesExtent(item.from, { limit: count, into: extent });
+    }
+  }
+  const range = chartPadExtent(extent);
+  // A stick is read from zero, so zero is on the chart whatever the values do.
+  return [Math.min(range.min, 0), Math.max(range.max, 0)];
+}
+
+/**
+ * A pixel back to the value it stands for.
+ * @param scale - Data to pixels.
+ * @param pixel - Where the pointer is.
+ * @returns The value.
+ */
+export function valueAt(scale: ChartScale, pixel: number): number {
+  return scale.factor === 0
+    ? Number.NaN
+    : (pixel - scale.offset) / scale.factor;
+}
+
+function round(pixel: number): number {
+  return Math.round(pixel * 10) / 10;
+}

package/src/chart/ui/useWheelZoom.ts

@@ -0,0 +1,177 @@
+import type { RefObject } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+import { CHART_WHEEL_SPEED, chartWheelFactor } from '../core/chartViewport.ts';
+
+/** How long the pointer rests on a chart before its wheel is caught, in ms. */
+export const CHART_WHEEL_DWELL = 500;
+
+/** What {@link useWheelZoom} needs. */
+export interface WheelZoomOptions {
+  /**
+   * Whether the wheel is caught at all.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * How long the pointer has to rest over the chart first, in milliseconds.
+   * @default CHART_WHEEL_DWELL
+   */
+  delay?: number;
+  /**
+   * Share zoomed per pixel of wheel travel.
+   * @default CHART_WHEEL_SPEED
+   */
+  speed?: number;
+  /**
+   * Called for every wheel event the chart caught: how far across the element
+   * the pointer was and how far down it, each from 0 to 1, and how much wider
+   * the frame should become — above one for a scroll away from the reader,
+   * below it for one towards them.
+   *
+   * The position is a share rather than a pixel because the element the wheel
+   * is caught on is the plot rectangle itself, so a share is already the share
+   * of the axis, and the caller needs no second measurement to anchor the zoom
+   * on the value under the pointer.
+   */
+  onZoom: (alongX: number, alongY: number, factor: number) => void;
+}
+
+/** A chart's wheel, and whether it is being listened to yet. */
+export interface WheelZoomApi<T extends Element> {
+  /** Put on the element the wheel is caught over — the plot's own surface. */
+  ref: RefObject<T | null>;
+  /**
+   * Whether the wheel is being caught right now, for a figure that wants to
+   * say so.
+   */
+  armed: boolean;
+}
+
+/**
+ * The wheel, caught only once the pointer has stayed a while.
+ *
+ * A chart that zooms the instant the pointer crosses it is a chart that steals
+ * the page scroll, and a reader who was on their way past a figure to the
+ * paragraph under it does not forgive that. Asking for a modifier avoids the
+ * theft but costs every reader the discovery: nothing on the picture says to
+ * hold a key down, so most never find out the figure zooms at all.
+ *
+ * So the wheel is caught after a dwell, and every wheel event that arrives
+ * before the dwell is up both scrolls the page and pushes the dwell out again.
+ * A reader scrolling through the page never rests, so the figure never takes
+ * their scroll, however slowly they pass over it — and the momentum a trackpad
+ * keeps sending after the fingers lift holds it off for exactly as long as it
+ * lasts. A reader who came to look at the picture has already rested on it by
+ * the time they reach for the wheel, and pays nothing.
+ *
+ * The listener is attached by hand rather than through `onWheel`, because
+ * React registers that one on the root as passive: `preventDefault` inside a
+ * JSX wheel handler does nothing at all, and the page would scroll under the
+ * zoom.
+ * @param options - See {@link WheelZoomOptions}.
+ * @returns The gesture. See {@link WheelZoomApi}.
+ */
+export function useWheelZoom<T extends Element>(
+  options: WheelZoomOptions,
+): WheelZoomApi<T> {
+  const {
+    enabled = true,
+    delay = CHART_WHEEL_DWELL,
+    speed = CHART_WHEEL_SPEED,
+    onZoom,
+  } = options;
+
+  const ref = useRef<T | null>(null);
+  const armedRef = useRef(false);
+  const [armed, setArmed] = useState(false);
+
+  // Held in a ref so the inline arrow every caller writes does not tear the
+  // listeners down and put them back on every render.
+  const zoom = useRef(onZoom);
+  useLayoutEffect(() => {
+    zoom.current = onZoom;
+  });
+
+  useEffect(() => {
+    const target = ref.current;
+    if (target === null || !enabled) return undefined;
+
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    function arm(state: boolean): void {
+      armedRef.current = state;
+      setArmed(state);
+    }
+    function rest(): void {
+      if (timer !== null) clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = null;
+        arm(true);
+      }, delay);
+    }
+    function forget(): void {
+      if (timer !== null) clearTimeout(timer);
+      timer = null;
+      arm(false);
+    }
+    function enter(): void {
+      if (!armedRef.current) rest();
+    }
+    // A pointer already resting over the plot when this was attached — a panel
+    // that has just been resized under it — never sends an enter event, so the
+    // dwell also starts on the first move that finds nothing pending. It must
+    // be the first: restarting it on every move would ask the reader to hold
+    // the pointer perfectly still, which is not what resting means.
+    function move(): void {
+      if (!armedRef.current && timer === null) rest();
+    }
+    // An arrow rather than a declaration, and typed as the plain `Event` the
+    // element's own listener map hands it: a hoisted function would be told
+    // the target might still be null, since it could in principle run before
+    // the guard above.
+    const wheel = (event: Event): void => {
+      if (!(event instanceof WheelEvent)) return;
+      // A wheel with a button down belongs to the drag that claimed the
+      // pointer: moving the ground under a lasso would leave the outline
+      // pointing at rows nobody drew a ring around.
+      if (event.buttons !== 0) return;
+      if (!armedRef.current) {
+        rest();
+        return;
+      }
+      event.preventDefault();
+      const box = target.getBoundingClientRect();
+      zoom.current(
+        share(event.clientX - box.left, box.width),
+        share(event.clientY - box.top, box.height),
+        chartWheelFactor(event.deltaY, event.deltaMode, speed),
+      );
+    };
+
+    target.addEventListener('pointerenter', enter);
+    target.addEventListener('pointermove', move);
+    target.addEventListener('pointerleave', forget);
+    target.addEventListener('wheel', wheel, { passive: false });
+    return () => {
+      forget();
+      target.removeEventListener('pointerenter', enter);
+      target.removeEventListener('pointermove', move);
+      target.removeEventListener('pointerleave', forget);
+      target.removeEventListener('wheel', wheel);
+    };
+  }, [enabled, delay, speed]);
+
+  return { ref, armed: enabled && armed };
+}
+
+/**
+ * How far along a side a position sits, from 0 to 1.
+ * @param position - The position, in pixels from the near edge.
+ * @param size - The side's length.
+ * @returns The share. The middle of an element with no size, which is the only
+ * place a pointer can be said to be on one.
+ */
+function share(position: number, size: number): number {
+  if (!(size > 0) || !Number.isFinite(position)) return 0.5;
+  return Math.min(1, Math.max(0, position / size));
+}

package/src/chrome/ui/index.ts

@@ -1,4 +1,7 @@
 export type { NavItem } from './navItem.ts';
+// A site drawing its own link needs the same reading of a click the shared nav
+// items use: a middle click or a modified one belongs to the browser.
+export { isModifiedClick } from './navItem.ts';
 export type { NavLinkProps } from './NavLink.tsx';
 export { NavLink } from './NavLink.tsx';
 export type { NavMenuButtonProps } from './NavMenuButton.tsx';

package/src/clipboard/ui/CodeBlock.tsx

@@ -19,7 +19,10 @@ const BASE_PRE_STYLE: CSSProperties = {
 
 const TONE_STYLE: Record<CodeBlockTone, CSSProperties> = {
   default: {},
-  muted: { background: '#f6f7f9', border: '1px solid #d3d8de' },
+  muted: {
+    background: 'var(--surface-sunken, #f6f7f9)',
+    border: '1px solid var(--border, #d3d8de)',
+  },
   dark: {
     background: '#1e293b',
     border: '1px solid #1e293b',

package/src/color/core/gradient.ts

@@ -0,0 +1,29 @@
+import type { ColorScale } from './interpolate.ts';
+import { sampleScale } from './interpolate.ts';
+
+const PERCENT = 100;
+const DECIMALS = 2;
+
+/**
+ * A colour scale written as the CSS gradient that draws it.
+ *
+ * The scale is sampled rather than handed over as its anchors, because a
+ * browser only interpolates the straight line between two colours: a scale
+ * that turns around the colour wheel would otherwise be drawn as the grey
+ * shortcut across it.
+ * @param scale - The scale to draw, from its low end at the left.
+ * @param samples - How many colours to write out; more of them for a scale that turns.
+ * @returns The `linear-gradient(…)` value.
+ * @throws {Error} When the scale has no anchor, or one of them is not a hex colour.
+ */
+export function colorScaleGradient(scale: ColorScale, samples: number): string {
+  const colors = sampleScale(scale, samples);
+  const last = colors.length - 1;
+  const stops: string[] = [];
+  for (let index = 0; index < colors.length; index++) {
+    const color = colors[index];
+    if (color === undefined) continue;
+    stops.push(`${color} ${((index / last) * PERCENT).toFixed(DECIMALS)}%`);
+  }
+  return `linear-gradient(to right, ${stops.join(', ')})`;
+}