react-cheminfo 0.8.0 → 0.10.0

package/lib/projection/ui/projectionViewChoices.js

@@ -0,0 +1,53 @@
+/**
+ * The four views of the "what differs" tab, and which of them a run can draw.
+ *
+ * The bar offers them and so does the panel behind the cog, and a list built
+ * twice is a list where one copy keeps offering a view the other has already
+ * learnt to grey out.
+ */
+/**
+ * The four views, each greyed with its reason when the run cannot draw it.
+ *
+ * A view whose data the run never reported is greyed rather than dropped, with
+ * the reason on the choice itself: a reader who cannot see that "Weights in
+ * your units" exists never learns to ask their colleague for a scaled model.
+ * @param copy - The words the viewer writes.
+ * @param available - See {@link ProjectionVariablesAvailability}.
+ * @returns The choices, in the order they are offered.
+ */
+export function projectionViewChoices(copy, available) {
+    const { canShowEffect, canRescale, canPickSample } = available;
+    const { view } = copy.bar;
+    return [
+        {
+            value: 'effect',
+            label: view.effect,
+            ...whenOff(canShowEffect, NO_AVERAGE),
+        },
+        { value: 'weights', label: view.weights },
+        {
+            value: 'rescaled',
+            label: view.rescaled,
+            ...whenOff(canRescale, NO_SCALES),
+        },
+        {
+            value: 'sample',
+            label: view.sample,
+            ...whenOff(canPickSample, NO_SAMPLE),
+        },
+    ];
+}
+/**
+ * A choice the run cannot support, greyed with the reason on it.
+ * @param available - Whether the data behind the choice is there.
+ * @param reason - What to tell a reader whose pointer cannot take it.
+ * @returns The two fields an unavailable choice carries, or neither.
+ */
+function whenOff(available, reason) {
+    return available ? {} : { disabled: true, title: reason };
+}
+/** Why a view is greyed, written as the thing the reader would have to change. */
+const NO_AVERAGE = 'Only when the run reported an average sample to push along the component.';
+const NO_SCALES = 'Only when the model divided each measurement by its spread.';
+const NO_SAMPLE = 'Select exactly one sample on the map first.';
+//# sourceMappingURL=projectionViewChoices.js.map

package/lib/projection/ui/projectionViewChoices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectionViewChoices.js","sourceRoot":"","sources":["../../../src/projection/ui/projectionViewChoices.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAoB,EACpB,SAA0C;IAE1C,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,EAAE,GAAG,SAAS,CAAC;IAC/D,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC;IAE1B,OAAO;QACL;YACE,KAAK,EAAE,QAAQ;YACf,KAAK,EAAE,IAAI,CAAC,MAAM;YAClB,GAAG,OAAO,CAAC,aAAa,EAAE,UAAU,CAAC;SACtC;QACD,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE;QACzC;YACE,KAAK,EAAE,UAAU;YACjB,KAAK,EAAE,IAAI,CAAC,QAAQ;YACpB,GAAG,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC;SAClC;QACD;YACE,KAAK,EAAE,QAAQ;YACf,KAAK,EAAE,IAAI,CAAC,MAAM;YAClB,GAAG,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC;SACrC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,OAAO,CACd,SAAkB,EAClB,MAAc;IAEd,OAAO,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;AAC5D,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,GACd,2EAA2E,CAAC;AAC9E,MAAM,SAAS,GAAG,6DAA6D,CAAC;AAChF,MAAM,SAAS,GAAG,6CAA6C,CAAC"}

package/lib/projection/ui/projectionViewerProps.d.ts

@@ -0,0 +1,153 @@
+/**
+ * What a caller hands a {@link ProjectionViewer}, and what it hands back.
+ *
+ * The types live beside the component rather than inside it because the shell
+ * is short and its options are not: a reader looking for what the viewer does
+ * should not have to scroll past a page of documented props to find it.
+ */
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionCopyPatch } from '../core/projectionCopyPatch.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import type { ProjectionResult } from '../core/projectionResult.ts';
+import type { ProjectionSamples } from '../core/projectionSamples.ts';
+import type { ProjectionTab } from '../core/projectionTabs.ts';
+import type { ProjectionVariableTrack } from './ProjectionVariablesTab.tsx';
+import type { ProjectionSelection } from './projectionSelection.ts';
+/** What {@link ProjectionViewer} needs. */
+export interface ProjectionViewerProps {
+    /** What the run produced, whatever produced it. */
+    result: ProjectionResult;
+    /** Who the rows are. */
+    samples: ProjectionSamples;
+    /**
+     * The tab showing. Present, the caller owns it, which is how a page puts the
+     * tab in its own URL.
+     * @default undefined — the viewer keeps its own
+     */
+    tab?: ProjectionTab;
+    /**
+     * Which panels the site offers, in any order.
+     *
+     * The viewer already hides a panel the result cannot fill, so this is for the
+     * other reason a panel should not be there: the page around it has no room,
+     * or has already said the same thing in its own words. Naming a panel the
+     * result cannot fill does not conjure it, and the map survives every filter —
+     * a viewer showing nothing at all is not a viewer.
+     *
+     * With one panel left there are no pills, so `panels={['map']}` is how a site
+     * embeds the scores plot and nothing else.
+     * @default undefined — every panel the result can fill
+     */
+    panels?: readonly ProjectionTab[];
+    /**
+     * The tab it opens on. A tab the result cannot fill, or that `panels` leaves
+     * out, is ignored.
+     * @default the first tab the result can fill
+     */
+    defaultTab?: ProjectionTab;
+    /**
+     * Called when the reader moves to another tab.
+     * @default undefined
+     */
+    onTabChange?: (tab: ProjectionTab) => void;
+    /**
+     * The selected rows, by name. Present, the caller owns the selection; the
+     * outline drawn while a lasso is being dragged stays inside the viewer
+     * either way.
+     * @default undefined — the viewer keeps its own
+     */
+    selected?: readonly string[];
+    /**
+     * The rows selected when it opens.
+     * @default undefined — nothing is selected
+     */
+    defaultSelected?: readonly string[];
+    /**
+     * Called when a lasso is released, a dot is clicked, a group is picked from
+     * the legend, or the selection is cleared — never while a lasso is being
+     * drawn, because a caller filtering a table behind it could not survive
+     * sixty calls a second. The rows arrive by name, so a caller never has to
+     * keep a second copy of the row order to read them.
+     * @default undefined
+     */
+    onSelectionChange?: (selection: ProjectionSelection) => void;
+    /**
+     * Called as the pointer crosses the "what differs" panels, and with `null`
+     * when it leaves. It fires on every measurement the pointer enters, so a
+     * caller doing real work in it — lighting a band on a spectrum beside the
+     * viewer — should hold the value in a ref rather than in state.
+     * @default undefined
+     */
+    onTrackVariable?: (track: ProjectionVariableTrack | null) => void;
+    /**
+     * Called with the row under the pointer on the map, or `null`. The card is
+     * drawn either way; this is for a page lighting up its own table.
+     * @default undefined
+     */
+    onHoverSample?: (id: string | null) => void;
+    /**
+     * What the figure is showing. Present, the caller owns every option, which
+     * is how a site persists them or writes them into a share link.
+     * @default undefined — the viewer keeps its own
+     */
+    options?: Partial<ProjectionOptions>;
+    /**
+     * The options it opens with, when it keeps its own.
+     * @default {}
+     */
+    defaultOptions?: Partial<ProjectionOptions>;
+    /**
+     * Called with every option after a change, not only the one that changed.
+     * @default undefined
+     */
+    onOptionsChange?: (options: ProjectionOptions) => void;
+    /**
+     * The words the viewer writes, merged over its own one key at a time.
+     * @default PROJECTION_COPY
+     */
+    copy?: ProjectionCopyPatch<ProjectionCopy>;
+    /**
+     * Height of the figure, in pixels. The width always follows the container.
+     * @default 460
+     */
+    height?: number;
+    /**
+     * How a number is written in a hover card and a readout.
+     * @default a rounding to three decimals with the trailing zeros dropped
+     */
+    formatValue?: (value: number) => string;
+    /**
+     * Whether a drag on a touch screen draws a lasso rather than scrolling the
+     * page.
+     * @default false
+     */
+    touchLasso?: boolean;
+    /**
+     * Whether the wheel zooms the map about the pointer, once the pointer has
+     * rested on the picture for half a second. On, because the viewer is given a
+     * panel of its own; a page that sets it in a column of prose should turn it
+     * off, so that a reader on their way past the figure keeps their scroll.
+     * @default true
+     */
+    wheelZoom?: boolean;
+    /**
+     * What a figure saved from the bar is called, without its extension; the
+     * view it was saved from is added to it, so the map of a run called
+     * `ecstasy` arrives as `ecstasy-map.png`. Name it after the data rather than
+     * after the tool: a reader with four of these in a downloads folder cannot
+     * tell four `projection-map.png` apart.
+     * @default 'projection'
+     */
+    fileName?: string;
+    /**
+     * Class the viewer carries, in addition to `projection-viewer`.
+     * @default undefined
+     */
+    className?: string;
+    /**
+     * Value of the `data-testid` attribute of the viewer.
+     * @default undefined
+     */
+    testId?: string;
+}
+//# sourceMappingURL=projectionViewerProps.d.ts.map

package/lib/projection/ui/projectionViewerProps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectionViewerProps.d.ts","sourceRoot":"","sources":["../../../src/projection/ui/projectionViewerProps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AACpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,2CAA2C;AAC3C,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,MAAM,EAAE,gBAAgB,CAAC;IACzB,wBAAwB;IACxB,OAAO,EAAE,iBAAiB,CAAC;IAC3B;;;;OAIG;IACH,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAClC;;;;OAIG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;IAC3B;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,CAAC;IAC3C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B;;;OAGG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,mBAAmB,KAAK,IAAI,CAAC;IAC7D;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,uBAAuB,GAAG,IAAI,KAAK,IAAI,CAAC;IAClE;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAC5C;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACrC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC5C;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;IACvD;;;OAGG;IACH,IAAI,CAAC,EAAE,mBAAmB,CAAC,cAAc,CAAC,CAAC;IAC3C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACxC;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/lib/projection/ui/projectionViewerProps.js

@@ -0,0 +1,9 @@
+/**
+ * What a caller hands a {@link ProjectionViewer}, and what it hands back.
+ *
+ * The types live beside the component rather than inside it because the shell
+ * is short and its options are not: a reader looking for what the viewer does
+ * should not have to scroll past a page of documented props to find it.
+ */
+export {};
+//# sourceMappingURL=projectionViewerProps.js.map

package/lib/projection/ui/projectionViewerProps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"projectionViewerProps.js","sourceRoot":"","sources":["../../../src/projection/ui/projectionViewerProps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/lib/projection/ui/useProjectionState.d.ts

@@ -0,0 +1,63 @@
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+import type { SelectionChange } from '../../scatter/ui/useScatterSelection.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
+import type { ProjectionTab } from '../core/projectionTabs.ts';
+import type { ProjectionSelection } from './projectionSelection.ts';
+import type { ProjectionViewerProps } from './projectionViewerProps.ts';
+/**
+ * What {@link useProjectionState} needs: the run, the rows, and the three
+ * pieces of state a caller may take over.
+ *
+ * It is the viewer's own props narrowed rather than a second list of the same
+ * eleven fields, so a default documented on the component is the default the
+ * hook actually applies and the two cannot drift apart.
+ */
+export type ProjectionStateOptions = Pick<ProjectionViewerProps, 'result' | 'samples' | 'tab' | 'defaultTab' | 'onTabChange' | 'selected' | 'defaultSelected' | 'onSelectionChange' | 'options' | 'panels' | 'defaultOptions' | 'onOptionsChange'>;
+/** What every tab reads, and the five ways any of them changes it. */
+export interface ProjectionStateApi {
+    /** The tabs this result can fill, in reading order. */
+    tabs: readonly ProjectionTab[];
+    /** The one showing. */
+    tab: ProjectionTab;
+    /** Move to another tab. One the result cannot fill is ignored. */
+    setTab: (tab: ProjectionTab) => void;
+    /** The groups as every figure draws them, resolved once per change. */
+    groups: ResolvedProjectionGroups;
+    /** Every option, already made safe against the result. */
+    options: ProjectionOptions;
+    /** Change some of them; the rest are carried over and checked again. */
+    setOptions: (patch: Partial<ProjectionOptions>) => void;
+    /** The selected rows, as indices, which is what a plot draws. */
+    selected: readonly number[];
+    /** Settle a selection a plot's own gesture produced. */
+    settleSelection: (change: SelectionChange) => void;
+    /** Settle one from elsewhere — a legend entry, a table beside the figure. */
+    selectRows: (rows: readonly number[], mode: ScatterSelectionMode, source: ProjectionSelection['source']) => void;
+    /** Draw one pair of axes on the map, which is what a cell of the grid does. */
+    selectPair: (xAxis: number, yAxis: number) => void;
+}
+/**
+ * The tab, the pair of axes, the selection and the options, controlled or not.
+ *
+ * The tabs are one tool only while they agree, which is why this is one hook
+ * and not four pieces of state in the shell: a pair promoted from the grid has
+ * to arrive on the map, and a lasso drawn there has to still be selected when
+ * the reader comes back to it.
+ *
+ * Each of tab, selection and options is owned by the caller from the moment
+ * its prop is passed and by the hook otherwise, and the two are never mixed: a
+ * controlled value wins on every render, so a caller told about a change that
+ * does not pass the new value back sees the figure stay where it was, rather
+ * than drift out of step with the address bar it is driven from. A `default`
+ * is read once, when the viewer mounts, and changing it later moves nothing.
+ *
+ * Selections cross this boundary as names rather than row numbers. A caller
+ * lighting up its own table already holds the names; handing back indices
+ * would make it keep a second copy of the row order, and that copy is exactly
+ * what goes stale the first time the data behind it is filtered.
+ * @param options - See {@link ProjectionStateOptions}.
+ * @returns The shared state. See {@link ProjectionStateApi}.
+ */
+export declare function useProjectionState(options: ProjectionStateOptions): ProjectionStateApi;
+//# sourceMappingURL=useProjectionState.d.ts.map

package/lib/projection/ui/useProjectionState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useProjectionState.d.ts","sourceRoot":"","sources":["../../../src/projection/ui/useProjectionState.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wCAAwC,CAAC;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEtE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAE7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAG/D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAMpE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG,IAAI,CACvC,qBAAqB,EACnB,QAAQ,GACR,SAAS,GACT,KAAK,GACL,YAAY,GACZ,aAAa,GACb,UAAU,GACV,iBAAiB,GACjB,mBAAmB,GACnB,SAAS,GACT,QAAQ,GACR,gBAAgB,GAChB,iBAAiB,CACpB,CAAC;AAEF,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/B,uBAAuB;IACvB,GAAG,EAAE,aAAa,CAAC;IACnB,kEAAkE;IAClE,MAAM,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,CAAC;IACrC,uEAAuE;IACvE,MAAM,EAAE,wBAAwB,CAAC;IACjC,0DAA0D;IAC1D,OAAO,EAAE,iBAAiB,CAAC;IAC3B,wEAAwE;IACxE,UAAU,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,iBAAiB,CAAC,KAAK,IAAI,CAAC;IACxD,iEAAiE;IACjE,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,wDAAwD;IACxD,eAAe,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IACnD,6EAA6E;IAC7E,UAAU,EAAE,CACV,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,oBAAoB,EAC1B,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAAC,KAClC,IAAI,CAAC;IACV,+EAA+E;IAC/E,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,sBAAsB,GAC9B,kBAAkB,CA0GpB"}

package/lib/projection/ui/useProjectionState.js

@@ -0,0 +1,107 @@
+import { useCallback, useMemo, useState } from 'react';
+import { resolveProjectionOptions } from "../core/projectionOptions.js";
+import { resolveProjectionGroups } from "../core/projectionSamples.js";
+import { projectionTabs } from "../core/projectionTabs.js";
+import { indexProjectionIds, projectionNamesOf, projectionRowsOf, } from "./projectionSelection.js";
+/**
+ * The tab, the pair of axes, the selection and the options, controlled or not.
+ *
+ * The tabs are one tool only while they agree, which is why this is one hook
+ * and not four pieces of state in the shell: a pair promoted from the grid has
+ * to arrive on the map, and a lasso drawn there has to still be selected when
+ * the reader comes back to it.
+ *
+ * Each of tab, selection and options is owned by the caller from the moment
+ * its prop is passed and by the hook otherwise, and the two are never mixed: a
+ * controlled value wins on every render, so a caller told about a change that
+ * does not pass the new value back sees the figure stay where it was, rather
+ * than drift out of step with the address bar it is driven from. A `default`
+ * is read once, when the viewer mounts, and changing it later moves nothing.
+ *
+ * Selections cross this boundary as names rather than row numbers. A caller
+ * lighting up its own table already holds the names; handing back indices
+ * would make it keep a second copy of the row order, and that copy is exactly
+ * what goes stale the first time the data behind it is filtered.
+ * @param options - See {@link ProjectionStateOptions}.
+ * @returns The shared state. See {@link ProjectionStateApi}.
+ */
+export function useProjectionState(options) {
+    const { result, samples, tab, defaultTab, onTabChange, selected, defaultSelected, onSelectionChange, options: heldOptions, defaultOptions, onOptionsChange, panels, } = options;
+    const { ids } = samples;
+    const tabs = useMemo(() => projectionTabs(result, panels), [result, panels]);
+    const rowOfId = useMemo(() => indexProjectionIds(ids), [ids]);
+    const [ownTab, setOwnTab] = useState(defaultTab);
+    const [ownSelected, setOwnSelected] = useState(() => projectionRowsOf(defaultSelected, rowOfId));
+    const [ownOptions, setOwnOptions] = useState(() => defaultOptions ?? {});
+    const groups = useMemo(() => resolveProjectionGroups(samples, result.scores.rows), [result, samples]);
+    const settled = useMemo(() => resolveProjectionOptions(heldOptions ?? ownOptions, result), [heldOptions, ownOptions, result]);
+    const setTab = useCallback((wanted) => {
+        const reachable = inReach(wanted, tabs);
+        if (reachable === undefined)
+            return;
+        if (tab === undefined)
+            setOwnTab(reachable);
+        onTabChange?.(reachable);
+    }, [onTabChange, tab, tabs]);
+    const setOptions = useCallback((patch) => {
+        const next = resolveProjectionOptions({ ...settled, ...patch }, result);
+        if (heldOptions === undefined)
+            setOwnOptions(next);
+        onOptionsChange?.(next);
+    }, [heldOptions, onOptionsChange, result, settled]);
+    const selectRows = useCallback((rows, mode, source) => {
+        if (selected === undefined)
+            setOwnSelected(rows);
+        onSelectionChange?.({
+            ids: projectionNamesOf(rows, ids),
+            indices: rows,
+            mode,
+            source,
+        });
+    }, [ids, onSelectionChange, selected]);
+    const settleSelection = useCallback((change) => {
+        selectRows(change.indices, change.mode, change.source);
+    }, [selectRows]);
+    const selectPair = useCallback((xAxis, yAxis) => {
+        setOptions({ xAxis, yAxis });
+        setTab('map');
+    }, [setOptions, setTab]);
+    return {
+        tabs,
+        // The last resort is the first tab offered, never the map: a site that
+        // narrowed `panels` away from it would otherwise be shown the one panel it
+        // said it had no room for, under a strip that does not name it.
+        tab: inReach(tab, tabs) ?? inReach(ownTab, tabs) ?? tabs[0] ?? 'map',
+        setTab,
+        groups,
+        options: settled,
+        setOptions,
+        selected: selected === undefined
+            ? ownSelected
+            : projectionRowsOf(selected, rowOfId),
+        settleSelection,
+        selectRows,
+        selectPair,
+    };
+}
+/**
+ * The wanted tab, when the result can actually fill it.
+ *
+ * A saved tab outlives the data it was saved on: a page reopening on the
+ * shares tab and handed a UMAP would otherwise show an empty panel with no
+ * obvious way back, so an unreachable tab is answered with nothing and the
+ * caller falls through to the first tab there is.
+ * @param wanted - The tab asked for, if any.
+ * @param tabs - The tabs the result can fill.
+ * @returns The tab, or `undefined` when it is not one of them.
+ */
+function inReach(wanted, tabs) {
+    if (wanted === undefined)
+        return undefined;
+    for (const tab of tabs) {
+        if (tab === wanted)
+            return wanted;
+    }
+    return undefined;
+}
+//# sourceMappingURL=useProjectionState.js.map

package/lib/projection/ui/useProjectionState.js.map

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

package/lib/scatter/core/confidenceEllipse.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The outline that summarises where a group of samples sits on a scatter plot.
+ *
+ * Everything here is in data units. Turning one of these into something an SVG
+ * can draw is `projectEllipse`, which has to be a separate step because the two
+ * axes rarely carry the same number of pixels per unit.
+ */
+/** A point of a cloud, or of an outline drawn around one, in data units. */
+export interface EllipsePoint {
+    /** Position along the horizontal axis. */
+    x: number;
+    /** Position along the vertical axis. */
+    y: number;
+}
+/** An outline drawn to hold a share of its group. */
+export interface EllipseCoverageSize {
+    /** Marks which of the two ways of asking for a size this is. */
+    kind: 'coverage';
+    /** The share of the group to enclose, from 0 to 1. */
+    probability: number;
+}
+/** An outline drawn at a multiple of its group's spread. */
+export interface EllipseStandardDeviationSize {
+    /** Marks which of the two ways of asking for a size this is. */
+    kind: 'standardDeviations';
+    /** How far out to draw, in standard deviations. */
+    standardDeviations: number;
+}
+/**
+ * How large a group outline is drawn.
+ *
+ * A share is what a reader understands without being taught, and it is the
+ * only mode the shipped control offers; the multiple is kept because a site
+ * whose audience already reads standard deviations should not have to convert
+ * one into the other by hand.
+ */
+export type EllipseSize = EllipseCoverageSize | EllipseStandardDeviationSize;
+/** How a cloud is spread, as the three distinct entries of its covariance. */
+export interface EllipseCovariance {
+    /** The spread along the horizontal axis. */
+    xx: number;
+    /** How the two axes move together; zero when they are unrelated. */
+    xy: number;
+    /** The spread along the vertical axis. */
+    yy: number;
+}
+/** A group outline, in data units. */
+export interface ConfidenceEllipse {
+    /** Centre of the outline, which is the group's average. */
+    cx: number;
+    /** Centre of the outline, which is the group's average. */
+    cy: number;
+    /** Semi-major axis length. */
+    rx: number;
+    /** Semi-minor axis length; exactly `0` when the group is collinear. */
+    ry: number;
+    /** Rotation of the major axis, in radians counter-clockwise, in `(-π/2, π/2]`. */
+    angle: number;
+    /** How many points went into it, the ones that were not finite left out. */
+    count: number;
+    /** The spread the outline was built from, before any size was applied. */
+    covariance: EllipseCovariance;
+}
+/** How {@link confidenceEllipse} measures a group. */
+export interface ConfidenceEllipseOptions {
+    /**
+     * How large to draw the outline.
+     * @default { kind: 'coverage', probability: 0.95 }
+     */
+    size?: EllipseSize;
+    /**
+     * How many finite points a group needs before it is outlined at all. Below
+     * it the shape says more about the sample than about the group. Fewer than
+     * two is read as two, because one point has no spread to measure.
+     * @default 3
+     */
+    minimumPoints?: number;
+}
+/**
+ * The outline that summarises a group of samples.
+ *
+ * Points that are not finite are skipped rather than poisoning the average, so
+ * a column with a few gaps still describes its group; `count` reports how many
+ * were actually used. The spread is measured with the `n - 1` divisor, which
+ * is what makes the outline an estimate of the group rather than a statement
+ * about the handful of samples that happen to have been measured.
+ * @param points - The group's samples, in data units.
+ * @param options - See {@link ConfidenceEllipseOptions}.
+ * @returns The outline, or `null` when the group is too small to have a shape, or when its coordinates are so large that squaring them overflows, or when the requested size is unbounded.
+ */
+export declare function confidenceEllipse(points: readonly EllipsePoint[], options?: ConfidenceEllipseOptions): ConfidenceEllipse | null;
+/**
+ * The semi-axes and the rotation that a covariance describes.
+ *
+ * The shape of an outline is the eigen-decomposition of a symmetric two by two
+ * matrix, which has a closed form and so never needs an iterative solver. It
+ * is public because the same three numbers are what turns any covariance into
+ * something drawable — one measured elsewhere, or one already mapped into
+ * pixels.
+ * @param covariance - How the cloud is spread.
+ * @param standardDeviations - How far out to measure. Defaults to `1`.
+ * @returns The two semi-axis lengths and the rotation of the major one, in radians, in `(-π/2, π/2]`. A collinear cloud gives `ry` of exactly `0`, and one with no spread at all gives an angle of `0` because it has no direction to report.
+ */
+export declare function ellipseAxes(covariance: EllipseCovariance, standardDeviations?: number): Pick<ConfidenceEllipse, 'rx' | 'ry' | 'angle'>;
+/**
+ * How far out an outline of a given size is drawn.
+ *
+ * Public because a figure that measures its groups itself — a pair grid
+ * decomposing one shared block of covariances rather than calling
+ * {@link confidenceEllipse} per cell — still has to honour the same size the
+ * map was asked for, and a second reading of `EllipseSize` would be a second
+ * place for the two to drift apart.
+ * @param size - How large the outline was asked to be.
+ * @returns The number of standard deviations, never below zero.
+ */
+export declare function ellipseStandardDeviations(size: EllipseSize): number;
+//# sourceMappingURL=confidenceEllipse.d.ts.map

package/lib/scatter/core/confidenceEllipse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"confidenceEllipse.d.ts","sourceRoot":"","sources":["../../../src/scatter/core/confidenceEllipse.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,CAAC,EAAE,MAAM,CAAC;IACV,wCAAwC;IACxC,CAAC,EAAE,MAAM,CAAC;CACX;AAED,qDAAqD;AACrD,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,IAAI,EAAE,UAAU,CAAC;IACjB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,4DAA4D;AAC5D,MAAM,WAAW,4BAA4B;IAC3C,gEAAgE;IAChE,IAAI,EAAE,oBAAoB,CAAC;IAC3B,mDAAmD;IACnD,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,4BAA4B,CAAC;AAE7E,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,4CAA4C;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC;IACX,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,UAAU,EAAE,iBAAiB,CAAC;CAC/B;AAED,sDAAsD;AACtD,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,OAAO,GAAE,wBAA6B,GACrC,iBAAiB,GAAG,IAAI,CAmD1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,iBAAiB,EAC7B,kBAAkB,SAAI,GACrB,IAAI,CAAC,iBAAiB,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,CAahD;AAiBD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAKnE"}