react-cheminfo 0.9.0 → 0.10.0

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/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(', ')})`;
+}

package/src/color/core/hsv.ts

@@ -0,0 +1,112 @@
+import type { RgbColor } from './hex.ts';
+
+const TURN = 360;
+const SECTOR = 60;
+const MAXIMUM_CHANNEL = 255;
+
+/**
+ * A colour in the HSV model — HSB in a drawing program, the same three numbers.
+ *
+ * It is the model a scale is customised in: hue says which colour, and the two
+ * others say how strong and how bright it is, so an author moves along the
+ * wheel without having to think in red, green and blue at once.
+ */
+export interface HsvColor {
+  /** Where it sits on the wheel, in degrees from 0 to 360. Zero on a grey. */
+  hue: number;
+  /** How far it is from grey, from 0 to 1. */
+  saturation: number;
+  /** How bright it is, from 0 for black to 1. */
+  value: number;
+}
+
+/**
+ * Read three channels as a hue, a saturation and a value.
+ * @param color - The three channels, each from 0 to 255.
+ * @returns The same colour in the HSV model.
+ */
+export function rgbToHsv(color: RgbColor): HsvColor {
+  const red = channel(color.red);
+  const green = channel(color.green);
+  const blue = channel(color.blue);
+  const value = Math.max(red, green, blue);
+  const chroma = value - Math.min(red, green, blue);
+  return {
+    hue: hueOf(red, green, blue, value, chroma),
+    saturation: value === 0 ? 0 : chroma / value,
+    value,
+  };
+}
+
+/**
+ * Write a hue, a saturation and a value back as three channels.
+ *
+ * The hue is wrapped rather than clamped, so a scale may run past 360 or below
+ * zero and still land on the colour that turn of the wheel names.
+ * @param color - The colour in the HSV model.
+ * @returns The three channels, each from 0 to 255.
+ */
+export function hsvToRgb(color: HsvColor): RgbColor {
+  const hue = wrapHue(color.hue) / SECTOR;
+  const saturation = unit(color.saturation);
+  const value = unit(color.value);
+  const sector = Math.floor(hue) % 6;
+  const offset = hue - Math.floor(hue);
+  const low = value * (1 - saturation);
+  const falling = value * (1 - saturation * offset);
+  const rising = value * (1 - saturation * (1 - offset));
+
+  if (sector === 0) return scale(value, rising, low);
+  if (sector === 1) return scale(falling, value, low);
+  if (sector === 2) return scale(low, value, rising);
+  if (sector === 3) return scale(low, falling, value);
+  if (sector === 4) return scale(rising, low, value);
+  return scale(value, low, falling);
+}
+
+/**
+ * A hue brought inside one turn of the wheel.
+ * @param hue - Any angle in degrees, negative or past 360.
+ * @returns The same angle, from 0 up to but not including 360.
+ */
+export function wrapHue(hue: number): number {
+  if (!Number.isFinite(hue)) return 0;
+  return ((hue % TURN) + TURN) % TURN;
+}
+
+function hueOf(
+  red: number,
+  green: number,
+  blue: number,
+  value: number,
+  chroma: number,
+): number {
+  if (chroma === 0) return 0;
+  let hue: number;
+  if (value === red) {
+    hue = (green - blue) / chroma;
+  } else if (value === green) {
+    hue = 2 + (blue - red) / chroma;
+  } else {
+    hue = 4 + (red - green) / chroma;
+  }
+  return wrapHue(hue * SECTOR);
+}
+
+function scale(red: number, green: number, blue: number): RgbColor {
+  return {
+    red: red * MAXIMUM_CHANNEL,
+    green: green * MAXIMUM_CHANNEL,
+    blue: blue * MAXIMUM_CHANNEL,
+  };
+}
+
+function channel(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value / MAXIMUM_CHANNEL));
+}
+
+function unit(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value));
+}

package/src/color/core/index.ts

@@ -1,9 +1,35 @@
 export type { ReadableInkOptions } from './contrast.ts';
 export { contrastRatio, readableInk, relativeLuminance } from './contrast.ts';
-export type { PositionInRangeOptions, Swatch } from './scale.ts';
+export type { RgbColor } from './hex.ts';
+export { parseHexColor, toHexColor } from './hex.ts';
+export { colorScaleGradient } from './gradient.ts';
+export type { HsvColor } from './hsv.ts';
+export { hsvToRgb, rgbToHsv, wrapHue } from './hsv.ts';
+export type {
+  ColorInterpolation,
+  ColorScale,
+  ColorStop,
+  Swatch,
+} from './interpolate.ts';
+export { colorAt, evenScale, sampleScale, swatchAt } from './interpolate.ts';
+export type { PositionInRangeOptions } from './scale.ts';
 export {
   VIRIDIS_SCALE,
   colorFromScale,
   positionInRange,
   swatchFromScale,
 } from './scale.ts';
+export type { ColorScaleKind, NamedColorScale } from './scales.ts';
+export {
+  COLOR_SCALES,
+  COLOR_SCALE_KIND_LABELS,
+  DEFAULT_COLOR_SCALE_ID,
+  colorScaleById,
+} from './scales.ts';
+export type { ResolvedColorScale } from './scaleText.ts';
+export {
+  MAXIMUM_CUSTOM_STOPS,
+  formatColorScale,
+  parseColorScale,
+  resolveColorScale,
+} from './scaleText.ts';