react-cheminfo 0.28.0 → 0.29.0

package/lib/chart/ui/useChartPointer.js

@@ -0,0 +1,152 @@
+/**
+ * Where the pointer is over a chart, and what that place means.
+ *
+ * What it *means* is the one thing this hook does not decide. A mass spectrum
+ * reads an m/z, an intensity and the peak within reach; an infrared spectrum
+ * reads a wavenumber, an absorbance and the band it falls in. Both are the same
+ * mechanism — place the pointer in user units, refuse the margins, and report
+ * only when the answer changed — so the mechanism is here and the reading is
+ * handed in.
+ *
+ * Every value is compared before it is stored or reported. A pointer resting on
+ * one feature fires `pointermove` on every sub-pixel tremor of a hand, and a
+ * fresh answer each time would re-render the panel beside the chart — and, where
+ * that panel is a linked viewer that reports its own hovers back, would
+ * ping-pong between the two until the tab stops answering.
+ */
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { svgPointAt } from "../core/svgPoint.js";
+/**
+ * Follow the pointer over a chart.
+ *
+ * The listeners are attached to the element rather than returned as props, so
+ * that a chart already spreading another hook's `onPointerMove` onto its SVG
+ * does not have to merge two handlers into one — and so that the options are
+ * read live, at the moment the pointer moves, rather than closed over when the
+ * listener was attached.
+ *
+ * The pointer leaving is heard as `pointerout` and not as the `pointerleave`
+ * that reads so much more naturally, because a chart with a control laid over
+ * it — a legend whose rows answer a hover — has two writers of one highlight
+ * and they must be sequenced. React synthesises the overlay's `pointerenter`
+ * from the *earlier* `pointerout` and dispatches it at the root, so a browser
+ * fires `pointerout` on the SVG, then React's `onPointerEnter` on the row, then
+ * `pointerleave` on the SVG: listening for the leave puts this hook's "nothing
+ * is under the pointer" **after** the row's "this trace is being read", and
+ * wipes it. Heard as `pointerout`, the report lands first and the row has the
+ * last word. The containment test is what `pointerleave` was giving for free.
+ * @param options - The chart, and how to read a point on it.
+ * @returns Where the pointer is and what it reads, both `null` while it is
+ * anywhere but over the plot.
+ */
+export function useChartPointer(options) {
+    const { svgRef } = options;
+    const [pointer, setPointer] = useState(POINTER_AWAY);
+    const latest = useRef(options);
+    const reported = useRef(null);
+    useLayoutEffect(() => {
+        latest.current = options;
+    });
+    useEffect(() => {
+        const svg = svgRef.current;
+        if (svg === null)
+            return;
+        function show(next) {
+            const { sameReadout, onReadout } = latest.current;
+            setPointer((current) => nextChartPointer(current, next, sameReadout));
+            if (sameReading(reported.current, next.readout, sameReadout))
+                return;
+            reported.current = next.readout;
+            onReadout?.(next.readout);
+        }
+        function move(event) {
+            const { plot, read } = latest.current;
+            const point = svgPointAt(svg, event.clientX, event.clientY);
+            show(point === null || !isInsidePlot(plot, point)
+                ? POINTER_AWAY
+                : { position: point, readout: read(point) });
+        }
+        function out(event) {
+            if (leftChart(svg, event.relatedTarget))
+                show(POINTER_AWAY);
+        }
+        svg.addEventListener('pointermove', move);
+        svg.addEventListener('pointerout', out);
+        return () => {
+            svg.removeEventListener('pointermove', move);
+            svg.removeEventListener('pointerout', out);
+        };
+    }, [svgRef]);
+    return pointer;
+}
+/**
+ * Whether a `pointerout` means the pointer has left the chart.
+ *
+ * It also fires on the way *into* a child of the SVG — a trace, a label, the
+ * rectangle behind a legend — which is not leaving the chart at all, and is the
+ * one thing `pointerleave` was giving for free.
+ * @param svg - The chart, `null` before it is on screen.
+ * @param related - What the pointer moved onto, `null` when it left the window
+ * altogether.
+ * @returns Whether the chart no longer has the pointer.
+ */
+export function leftChart(svg, related) {
+    if (svg === null)
+        return true;
+    return !(related instanceof Node) || !svg.contains(related);
+}
+/**
+ * Whether two readings — either of which may be absent — say the same thing.
+ * @param current - What was last read, `null` while the pointer was away.
+ * @param next - What has just been read, `null` when it has left the plot.
+ * @param sameReadout - The viewer's own comparison.
+ * @returns Whether the report can be skipped.
+ */
+export function sameReading(current, next, sameReadout) {
+    if (current === next)
+        return true;
+    if (current === null || next === null)
+        return false;
+    return sameReadout(current, next);
+}
+/**
+ * What to hold, given where the pointer has just been seen.
+ *
+ * The answer already held comes back whenever it still stands, so the whole
+ * chart is left alone while a hand rests on a feature — `pointermove` fires on
+ * every tremor, and several of those land on the very same user-unit position.
+ * @param current - What is held.
+ * @param next - What has just been read.
+ * @param sameReadout - The viewer's own comparison, asked only once the pointer
+ * turns out not to have moved.
+ * @returns `current` itself when it already says it, `next` otherwise.
+ */
+export function nextChartPointer(current, next, sameReadout) {
+    if (current === next)
+        return current;
+    if (current.position === null || next.position === null) {
+        return current.position === next.position ? current : next;
+    }
+    if (current.position.x !== next.position.x ||
+        current.position.y !== next.position.y) {
+        return next;
+    }
+    return sameReading(current.readout, next.readout, sameReadout)
+        ? current
+        : next;
+}
+/**
+ * Whether a point is over the data rather than over an axis.
+ * @param plot - Where the plot sits inside the SVG.
+ * @param point - The point to test, in user units.
+ * @returns Whether it is inside the plot, edges included.
+ */
+export function isInsidePlot(plot, point) {
+    return (point.x >= plot.left &&
+        point.x <= plot.right &&
+        point.y >= plot.top &&
+        point.y <= plot.bottom);
+}
+/** What is held while the pointer is anywhere but over the plot. */
+const POINTER_AWAY = { position: null, readout: null };
+//# sourceMappingURL=useChartPointer.js.map

package/lib/chart/ui/useChartPointer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChartPointer.js","sourceRoot":"","sources":["../../../src/chart/ui/useChartPointer.ts"],"names":[],"mappings":"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"}

package/lib/chart/ui/useChartSize.d.ts

@@ -0,0 +1,49 @@
+/**
+ * How big the box a chart was handed is, followed for as long as it is on
+ * screen.
+ *
+ * The element is measured from the `ref` rather than from an effect, so the
+ * observer is re-attached every time the element goes away and comes back —
+ * which is the whole point of doing it here. A chart living in a folded
+ * accordion panel is unmounted while the panel is shut; an observer bound once
+ * at mount would be watching an element nobody kept, so the chart returns
+ * measuring nothing, builds its scales on a plot of `MINIMUM_PLOT_SIDE`, and
+ * stays that way until the window itself happens to be resized. Measuring in
+ * the callback also means the size is known in the same commit the element
+ * appears in, so nothing is ever painted at a size that is about to change.
+ */
+import type { ChartSize } from '../core/chartGeometry.ts';
+/** The `ref` to put on the wrapper, and how big that wrapper is. */
+export type ChartSizeHandle<T extends Element> = [
+    ref: (element: T | null) => void,
+    size: ChartSize
+];
+/**
+ * Follow the size of the element a chart is drawn in.
+ *
+ * The `ref` never changes between renders, so React attaches it once per
+ * element rather than detaching and re-attaching it — and a detach here is not
+ * free, since it is what tears the observer down.
+ * @returns The `ref`, and the size — `0 × 0` until the element is on screen,
+ * which every first render sees.
+ */
+export declare function useChartSize<T extends Element = HTMLDivElement>(): ChartSizeHandle<T>;
+/**
+ * The size to hold, given what the element has just been measured at.
+ *
+ * The one already held comes back when the numbers have not moved, so a
+ * resize that changes nothing — a splitter dragged and let go where it was, a
+ * panel folded and unfolded at the same width — costs a comparison rather than
+ * a render of the whole chart, which rebuilds every scale and re-lays every
+ * label out.
+ *
+ * A measurement that is not a size is read as nothing at all: a negative width
+ * is impossible, and a `NaN` one is what an element that is not laid out gives.
+ * Either would travel into `plotRect` and out the far side as an infinity.
+ * @param current - The size held so far.
+ * @param width - What the element has just been measured at, horizontally.
+ * @param height - What it has just been measured at, vertically.
+ * @returns `current` itself when nothing moved, the new size otherwise.
+ */
+export declare function nextChartSize(current: ChartSize, width: number, height: number): ChartSize;
+//# sourceMappingURL=useChartSize.d.ts.map

package/lib/chart/ui/useChartSize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChartSize.d.ts","sourceRoot":"","sources":["../../../src/chart/ui/useChartSize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAE1D,oEAAoE;AACpE,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,OAAO,IAAI;IAC/C,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI;IAChC,IAAI,EAAE,SAAS;CAChB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,CAAC,SAAS,OAAO,GAAG,cAAc,KAC/B,eAAe,CAAC,CAAC,CAAC,CAsBtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,EAClB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,SAAS,CAOX"}

package/lib/chart/ui/useChartSize.js

@@ -0,0 +1,91 @@
+/**
+ * How big the box a chart was handed is, followed for as long as it is on
+ * screen.
+ *
+ * The element is measured from the `ref` rather than from an effect, so the
+ * observer is re-attached every time the element goes away and comes back —
+ * which is the whole point of doing it here. A chart living in a folded
+ * accordion panel is unmounted while the panel is shut; an observer bound once
+ * at mount would be watching an element nobody kept, so the chart returns
+ * measuring nothing, builds its scales on a plot of `MINIMUM_PLOT_SIDE`, and
+ * stays that way until the window itself happens to be resized. Measuring in
+ * the callback also means the size is known in the same commit the element
+ * appears in, so nothing is ever painted at a size that is about to change.
+ */
+import { useCallback, useRef, useState } from 'react';
+/**
+ * Follow the size of the element a chart is drawn in.
+ *
+ * The `ref` never changes between renders, so React attaches it once per
+ * element rather than detaching and re-attaching it — and a detach here is not
+ * free, since it is what tears the observer down.
+ * @returns The `ref`, and the size — `0 × 0` until the element is on screen,
+ * which every first render sees.
+ */
+export function useChartSize() {
+    const observer = useRef(null);
+    const [size, setSize] = useState(NO_SIZE);
+    const measure = useCallback((element) => {
+        // Torn down here rather than from a cleanup returned to React: only React
+        // 19 runs one, where React 18 calls the ref with `null` instead — so
+        // detaching on `null` is what disconnects the observer under both.
+        observer.current?.disconnect();
+        observer.current = null;
+        if (element === null)
+            return;
+        read(element, setSize);
+        // Absent outside a browser, where nothing is on screen to be resized.
+        if (typeof ResizeObserver === 'undefined')
+            return;
+        observer.current = new ResizeObserver(() => {
+            read(element, setSize);
+        });
+        observer.current.observe(element);
+    }, []);
+    return [measure, size];
+}
+/**
+ * The size to hold, given what the element has just been measured at.
+ *
+ * The one already held comes back when the numbers have not moved, so a
+ * resize that changes nothing — a splitter dragged and let go where it was, a
+ * panel folded and unfolded at the same width — costs a comparison rather than
+ * a render of the whole chart, which rebuilds every scale and re-lays every
+ * label out.
+ *
+ * A measurement that is not a size is read as nothing at all: a negative width
+ * is impossible, and a `NaN` one is what an element that is not laid out gives.
+ * Either would travel into `plotRect` and out the far side as an infinity.
+ * @param current - The size held so far.
+ * @param width - What the element has just been measured at, horizontally.
+ * @param height - What it has just been measured at, vertically.
+ * @returns `current` itself when nothing moved, the new size otherwise.
+ */
+export function nextChartSize(current, width, height) {
+    const nextWidth = usableSide(width);
+    const nextHeight = usableSide(height);
+    if (current.width === nextWidth && current.height === nextHeight) {
+        return current;
+    }
+    return { width: nextWidth, height: nextHeight };
+}
+/** What a chart is given before its element has ever been laid out. */
+const NO_SIZE = { width: 0, height: 0 };
+/**
+ * Measure an element and hold what it says.
+ * @param element - The wrapper the chart is drawn in.
+ * @param setSize - Where the measurement goes.
+ */
+function read(element, setSize) {
+    const { width, height } = element.getBoundingClientRect();
+    setSize((current) => nextChartSize(current, width, height));
+}
+/**
+ * One side of a measurement, as a size rather than as a number.
+ * @param value - What the element was measured at.
+ * @returns The side, `0` for anything that is not a length.
+ */
+function usableSide(value) {
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+//# sourceMappingURL=useChartSize.js.map

package/lib/chart/ui/useChartSize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChartSize.js","sourceRoot":"","sources":["../../../src/chart/ui/useChartSize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAUtD;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY;IAG1B,MAAM,QAAQ,GAAG,MAAM,CAAwB,IAAI,CAAC,CAAC;IACrD,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAY,OAAO,CAAC,CAAC;IAErD,MAAM,OAAO,GAAG,WAAW,CAAC,CAAC,OAAiB,EAAE,EAAE;QAChD,0EAA0E;QAC1E,qEAAqE;QACrE,mEAAmE;QACnE,QAAQ,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC;QAC/B,QAAQ,CAAC,OAAO,GAAG,IAAI,CAAC;QACxB,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO;QAE7B,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACvB,sEAAsE;QACtE,IAAI,OAAO,cAAc,KAAK,WAAW;YAAE,OAAO;QAClD,QAAQ,CAAC,OAAO,GAAG,IAAI,cAAc,CAAC,GAAG,EAAE;YACzC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;AACzB,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,aAAa,CAC3B,OAAkB,EAClB,KAAa,EACb,MAAc;IAEd,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACjE,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;AAClD,CAAC;AAED,uEAAuE;AACvE,MAAM,OAAO,GAAc,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;AAEnD;;;;GAIG;AACH,SAAS,IAAI,CACX,OAAgB,EAChB,OAA4C;IAE5C,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAC1D,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC"}

package/lib/chart/ui/useChartWindow.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The window a chart is looking through, and the two scales it is read by.
+ *
+ * Three things can decide what is on screen — the fit the data asks for, the
+ * window a gesture arrived at, and a window a host imposes — and the whole of
+ * the policy that settles between them is here, away from the gestures, because
+ * it is the half that has nothing to do with a pointer. A chart put back to its
+ * fit by a toolbar button and one put back by a double click are the same event
+ * to this hook.
+ *
+ * The scales come out of the same place for a reason that shipped broken once:
+ * every gesture is measured by inverting a pixel, so a chart drawing a reversed
+ * axis while the gestures were measured through an ascending one zoomed to the
+ * mirror image of whatever was dragged over. Held here, beside the window they
+ * are built from, there is only ever one mapping to disagree with.
+ */
+import type { ChartDomain } from '../core/chartDomain.ts';
+import type { PlotRect } from '../core/chartGeometry.ts';
+import type { ChartScale } from '../core/chartScale.ts';
+/** The fit, the window a host imposes, and the box both are drawn into. */
+export interface ChartWindowOptions {
+    /**
+     * The window that shows everything currently drawn, as the viewer fits it.
+     * This is what a double click goes back to.
+     */
+    fitted: ChartDomain;
+    /**
+     * What that fit was made *to*, as one string two renders can compare.
+     *
+     * The window is put back to the fit whenever this changes and never otherwise,
+     * so it must name the data and not its extents: a spectrum switched from one
+     * unit to another, or from its profile to its sticks, moves the fitted extents
+     * by a hair, and refitting on a hair throws away the zoom somebody set.
+     */
+    fitKey: string;
+    /**
+     * What the **value axis alone** was fitted to, for a chart whose height is
+     * fitted to something that changes under a window the reader is keeping.
+     *
+     * A loading spectrum is the case it was written for. The reader zooms onto a
+     * few masses and then steps through the components, and the m/z window is
+     * where they are looking rather than a fact about the component being read —
+     * so it stays. The loading axis is fitted to the component's own scale, and
+     * cannot: drawn through the last component's window, a diffuse component is a
+     * flat line along the middle and a concentrated one is cut off at the top.
+     * @default `fitKey`, so the value axis moves only when the whole fit does
+     */
+    yFitKey?: string;
+    /** Where the plot sits inside the SVG, which the axes are laid over. */
+    plot: PlotRect;
+    /**
+     * The window a host is imposing, `null` while it imposes none.
+     *
+     * It is handed *in* rather than merely shown beside the chart's own, so that
+     * every gesture is measured against what is actually on screen. A peak table
+     * that frames a value, a handle that zooms to one: both put a window on the
+     * chart that the chart did not arrive at, and a drag worked out against the
+     * window the chart last held instead would zoom to somewhere else entirely.
+     * It is taken up when it *changes*, not held over the chart's own — see the
+     * hook itself for why that distinction is the difference between a chart that
+     * zooms and one that zooms once.
+     * @default null
+     */
+    domain?: ChartDomain | null;
+    /**
+     * Whether the horizontal axis is drawn right to left, as an infrared
+     * spectrum's wavenumbers are.
+     *
+     * It has to be said **here**, and this is the one option a viewer cannot get
+     * away with handling on its own: a chart that drew a reversed axis while the
+     * gestures were measured through an ascending one would zoom to the mirror
+     * image of whatever was dragged over. The scales are handed back for exactly
+     * that reason — draw with those and the two cannot disagree.
+     * @default false
+     */
+    reverseX?: boolean;
+}
+/** The window, how it maps to pixels, and the two ways it moves. */
+export interface ChartWindow {
+    /** What the chart is showing. */
+    domain: ChartDomain;
+    /** The horizontal axis, already accounting for a reversed one. */
+    xScale: ChartScale;
+    /** The vertical axis, which runs backwards because SVG counts downwards. */
+    yScale: ChartScale;
+    /** Show a window a gesture arrived at. */
+    show: (domain: ChartDomain) => void;
+    /** Put the window back to everything that is drawn. */
+    reset: () => void;
+}
+/**
+ * Hold the window a chart shows, and map it to the plot.
+ *
+ * The window is put back to what fits whenever the chart is handed **different
+ * data** — a spectrum loaded, one closed, the chart reflected about zero — and
+ * is otherwise left exactly where it was. That distinction is the whole of the
+ * behaviour, and `fitKey` is where it is drawn: the same spectra drawn
+ * differently is the same data, and a chart that refitted on it would throw away
+ * the window somebody had zoomed to for a change of a fraction of a percent in
+ * the extents.
+ *
+ * The value axis can be refitted on its own, by `yFitKey`, for the one chart
+ * where the two halves of the window answer to different things: a component's
+ * loadings are drawn on the component's own scale, while the masses on screen
+ * are where the reader chose to look and have nothing to do with which
+ * component is being read. Everywhere else it is the whole fit that moves, so
+ * it defaults to `fitKey` and nothing has to be said.
+ *
+ * A window a host imposes is **taken up as it changes**, and is not held over
+ * the window kept here. A host is told every window the chart arrives at and is
+ * expected to hand that same window back, so what it imposes is, in the ordinary
+ * case, the answer to the *last* gesture. Held over the top, that answer would
+ * be the answer to the next one as well — the chart would zoom once, report it,
+ * and then stand still, with every later drag and turn of the wheel worked out
+ * and thrown away.
+ *
+ * Handing back `null` where a window was is how a host asks for the fit again —
+ * the only thing it is ever told is a window, so that is the one way it has of
+ * saying it. That is what "zoom to fit" pressed on a toolbar beside the chart
+ * comes down to.
+ *
+ * New data refits the **value axis** of whatever a host is imposing, and leaves
+ * the horizontal half of it alone. A host that stores every window it is told
+ * and hands the same one back is imposing one at every moment after the first
+ * gesture, so a refit that waited for it to stop would never happen at all: a
+ * chart reflected about zero would draw its mirrored half below the foot of the
+ * plot, where the clip path swallows it. But the horizontal axis is where the
+ * reader chose to look, and by the time data arrives with a window still
+ * imposed the host has already decided the two belong together — every route in
+ * gives its own window up when what arrived does not belong in it, and there is
+ * then nothing imposed here to keep. What is left is another scan of the run
+ * being stepped through, or another pixel of the section being compared, and
+ * refitting those out of the window they are being compared in is the one thing
+ * the gesture that added them was not asking for. A host imposing a *different*
+ * window in the same render still wins outright, since it is asking for that
+ * window of the data just handed over.
+ *
+ * The imposed window is compared by value rather than by identity, so a host
+ * that rebuilds an equal window on every render neither fights the gestures nor
+ * renders forever. Both comparisons are made while rendering rather than in an
+ * effect: an effect would draw the stale window for one frame, and setting state
+ * from one is what `react-hooks/set-state-in-effect` forbids.
+ * @param options - The fit, the plot, and the window a host imposes.
+ * @returns The window, its two scales, and the two ways it is moved.
+ */
+export declare function useChartWindow(options: ChartWindowOptions): ChartWindow;
+//# sourceMappingURL=useChartWindow.d.ts.map

package/lib/chart/ui/useChartWindow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChartWindow.d.ts","sourceRoot":"","sources":["../../../src/chart/ui/useChartWindow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGxD,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,IAAI,EAAE,QAAQ,CAAC;IACf;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,oEAAoE;AACpE,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,MAAM,EAAE,WAAW,CAAC;IACpB,kEAAkE;IAClE,MAAM,EAAE,UAAU,CAAC;IACnB,4EAA4E;IAC5E,MAAM,EAAE,UAAU,CAAC;IACnB,0CAA0C;IAC1C,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;IACpC,uDAAuD;IACvD,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAwEvE"}

package/lib/chart/ui/useChartWindow.js

@@ -0,0 +1,135 @@
+/**
+ * The window a chart is looking through, and the two scales it is read by.
+ *
+ * Three things can decide what is on screen — the fit the data asks for, the
+ * window a gesture arrived at, and a window a host imposes — and the whole of
+ * the policy that settles between them is here, away from the gestures, because
+ * it is the half that has nothing to do with a pointer. A chart put back to its
+ * fit by a toolbar button and one put back by a double click are the same event
+ * to this hook.
+ *
+ * The scales come out of the same place for a reason that shipped broken once:
+ * every gesture is measured by inverting a pixel, so a chart drawing a reversed
+ * axis while the gestures were measured through an ascending one zoomed to the
+ * mirror image of whatever was dragged over. Held here, beside the window they
+ * are built from, there is only ever one mapping to disagree with.
+ */
+import { useCallback, useMemo, useState } from 'react';
+import { sameChartDomain } from "../core/chartDomain.js";
+import { chartScale } from "../core/chartScale.js";
+/**
+ * Hold the window a chart shows, and map it to the plot.
+ *
+ * The window is put back to what fits whenever the chart is handed **different
+ * data** — a spectrum loaded, one closed, the chart reflected about zero — and
+ * is otherwise left exactly where it was. That distinction is the whole of the
+ * behaviour, and `fitKey` is where it is drawn: the same spectra drawn
+ * differently is the same data, and a chart that refitted on it would throw away
+ * the window somebody had zoomed to for a change of a fraction of a percent in
+ * the extents.
+ *
+ * The value axis can be refitted on its own, by `yFitKey`, for the one chart
+ * where the two halves of the window answer to different things: a component's
+ * loadings are drawn on the component's own scale, while the masses on screen
+ * are where the reader chose to look and have nothing to do with which
+ * component is being read. Everywhere else it is the whole fit that moves, so
+ * it defaults to `fitKey` and nothing has to be said.
+ *
+ * A window a host imposes is **taken up as it changes**, and is not held over
+ * the window kept here. A host is told every window the chart arrives at and is
+ * expected to hand that same window back, so what it imposes is, in the ordinary
+ * case, the answer to the *last* gesture. Held over the top, that answer would
+ * be the answer to the next one as well — the chart would zoom once, report it,
+ * and then stand still, with every later drag and turn of the wheel worked out
+ * and thrown away.
+ *
+ * Handing back `null` where a window was is how a host asks for the fit again —
+ * the only thing it is ever told is a window, so that is the one way it has of
+ * saying it. That is what "zoom to fit" pressed on a toolbar beside the chart
+ * comes down to.
+ *
+ * New data refits the **value axis** of whatever a host is imposing, and leaves
+ * the horizontal half of it alone. A host that stores every window it is told
+ * and hands the same one back is imposing one at every moment after the first
+ * gesture, so a refit that waited for it to stop would never happen at all: a
+ * chart reflected about zero would draw its mirrored half below the foot of the
+ * plot, where the clip path swallows it. But the horizontal axis is where the
+ * reader chose to look, and by the time data arrives with a window still
+ * imposed the host has already decided the two belong together — every route in
+ * gives its own window up when what arrived does not belong in it, and there is
+ * then nothing imposed here to keep. What is left is another scan of the run
+ * being stepped through, or another pixel of the section being compared, and
+ * refitting those out of the window they are being compared in is the one thing
+ * the gesture that added them was not asking for. A host imposing a *different*
+ * window in the same render still wins outright, since it is asking for that
+ * window of the data just handed over.
+ *
+ * The imposed window is compared by value rather than by identity, so a host
+ * that rebuilds an equal window on every render neither fights the gestures nor
+ * renders forever. Both comparisons are made while rendering rather than in an
+ * effect: an effect would draw the stale window for one frame, and setting state
+ * from one is what `react-hooks/set-state-in-effect` forbids.
+ * @param options - The fit, the plot, and the window a host imposes.
+ * @returns The window, its two scales, and the two ways it is moved.
+ */
+export function useChartWindow(options) {
+    const { fitted, fitKey, yFitKey = fitKey, plot, domain: imposed = null, reverseX = false, } = options;
+    // What the chart shows, and the one thing every gesture moves.
+    const [held, setHeld] = useState(imposed ?? fitted);
+    const [fittedFor, setFittedFor] = useState(fitKey);
+    if (fittedFor !== fitKey) {
+        setFittedFor(fitKey);
+        // The horizontal half of a window a host is still imposing survives the
+        // refit; only the value axis is refitted. A host that wanted the whole
+        // window given up has already given it up — every route in clears its own
+        // window when the data that arrived does not belong in it, and then there
+        // is nothing imposed here to keep. What is left is the case where it does
+        // belong: another scan of the run being stepped through, another pixel of
+        // the section being compared. Refitting x there throws away the very
+        // window the reader is comparing *in*, which is the whole point of the
+        // gesture that added it.
+        //
+        // The value axis is refitted all the same, and must be: a chart reflected
+        // about zero, or one a brighter trace has just joined, is drawn against a
+        // height that has genuinely changed, and keeping the old one hides the new
+        // data below the foot of the plot or off the top of it.
+        setHeld((current) => imposed === null ? fitted : { x: current.x, y: fitted.y });
+    }
+    const [yFittedFor, setYFittedFor] = useState(yFitKey);
+    if (yFittedFor !== yFitKey) {
+        setYFittedFor(yFitKey);
+        // Mapped over whatever the refit above may just have set, rather than over
+        // the window this render read, so that both keys changing at once is the
+        // whole fit and not the last window's x with a new height on it.
+        setHeld((current) => ({ x: current.x, y: fitted.y }));
+    }
+    const [imposedShown, setImposedShown] = useState(imposed);
+    if (!sameImposedDomain(imposedShown, imposed)) {
+        setImposedShown(imposed);
+        setHeld(imposed ?? fitted);
+    }
+    const domain = held;
+    // Reversed by handing the range over backwards, which is the whole of drawing
+    // an axis right to left.
+    const xScale = useMemo(() => reverseX
+        ? chartScale(domain.x[0], domain.x[1], plot.right, plot.left)
+        : chartScale(domain.x[0], domain.x[1], plot.left, plot.right), [domain.x, plot.left, plot.right, reverseX]);
+    // Backwards, since SVG counts pixels downwards while a value counts up.
+    const yScale = useMemo(() => chartScale(domain.y[0], domain.y[1], plot.bottom, plot.top), [domain.y, plot.bottom, plot.top]);
+    const reset = useCallback(() => {
+        setHeld(fitted);
+    }, [fitted]);
+    return { domain, xScale, yScale, show: setHeld, reset };
+}
+/**
+ * Whether a host is imposing the same window it was imposing before.
+ * @param current - The window it imposed last, `null` when it imposed none.
+ * @param next - The window it imposes now, `null` for none.
+ * @returns Whether both say the same thing.
+ */
+function sameImposedDomain(current, next) {
+    if (current === null || next === null)
+        return current === next;
+    return sameChartDomain(current, next);
+}
+//# sourceMappingURL=useChartWindow.js.map

package/lib/chart/ui/useChartWindow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChartWindow.js","sourceRoot":"","sources":["../../../src/chart/ui/useChartWindow.ts"],"names":[],"mappings":"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"}