react-cheminfo 0.9.0 → 0.11.0

package/lib/projection/ui/projectionVariablesWords.js

@@ -0,0 +1,91 @@
+/**
+ * What the "what differs" tab says about its own panels: the sentence over
+ * them, the key naming their colours, and the name under the horizontal axis.
+ *
+ * They are separated from what the panels draw because every one of them is a
+ * claim about the picture rather than part of it, and a claim is worth reading
+ * — and testing — on its own. A caption that promises bars over a panel of
+ * lines is a bug nobody sees in a series array.
+ */
+import { fillCopy } from "../core/projectionCopy.js";
+/**
+ * The tab's own sentence, which has to describe the view the reader is looking
+ * at and the shape it is drawn in.
+ *
+ * Both matter, and neither can stand in for the other. Two of the four views
+ * draw a sample profile as a line whatever the measurements are, so a sentence
+ * chosen from the axis alone promises bars over a panel of lines. The other two
+ * draw weights, and there the axis decides: named measurements become bars and
+ * a number line stays a line.
+ * @param built - The panels as they were built, for the view and the axis.
+ * @param copy - The words the tab writes.
+ * @returns The sentence.
+ */
+export function variablesCaption(built, copy) {
+    const { axis, view } = built;
+    if (view === 'effect')
+        return copy.intro.variablesEffect;
+    if (view === 'sample')
+        return copy.intro.variablesSample;
+    if (axis.kind === 'named')
+        return copy.intro.variablesNamed;
+    return fillCopy(copy.intro.variablesContinuous, { axis: plural(axis.label) });
+}
+/**
+ * The sentence naming what colour and shape mean, which is the view's own.
+ * @param built - The panels as they were built.
+ * @param copy - The words the tab writes.
+ * @param sample - What the one selected sample is called.
+ * @returns The sentence.
+ */
+export function legendTitle(built, copy, sample) {
+    const { legend } = copy;
+    if (built.view === 'effect')
+        return legend.variablesEffect;
+    if (built.view === 'rescaled')
+        return legend.variablesRescaled;
+    if (built.view === 'sample') {
+        return fillCopy(legend.variablesSample, { sample });
+    }
+    return legend.variablesWeights;
+}
+/**
+ * Every drawn component as a line, and the average as a grey dashed one.
+ * @param built - The panels as they were built.
+ * @param average - Whether the average sample is drawn.
+ * @param copy - The words the tab writes.
+ * @returns The entries, in the panels' own order.
+ */
+export function legendEntries(built, average, copy) {
+    const entries = built.profiles.map((profile) => ({
+        id: `component-${profile.index}`,
+        label: profile.label,
+        color: profile.color,
+        shape: 'line',
+    }));
+    if (average) {
+        entries.push({
+            id: 'average',
+            label: copy.help.showAverage.title,
+            color: 'var(--text-faint)',
+            shape: 'dashed',
+        });
+    }
+    return entries;
+}
+/**
+ * What the horizontal axis measures, with its unit in brackets.
+ * @param axis - How the measurements are laid out.
+ * @returns The axis title.
+ */
+export function axisCaption(axis) {
+    if (axis.kind === 'named')
+        return axis.label ?? 'Measurement';
+    const unit = axis.unit ?? '';
+    return unit === '' ? axis.label : `${axis.label} (${unit})`;
+}
+function plural(word) {
+    const lower = word.toLowerCase();
+    return lower.endsWith('s') ? lower : `${lower}s`;
+}
+//# sourceMappingURL=projectionVariablesWords.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projectionVariablesWords.js","sourceRoot":"","sources":["../../../src/projection/ui/projectionVariablesWords.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAGrD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAsB,EACtB,IAAoB;IAEpB,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAC7B,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC;IACzD,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC;IACzD,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC;IAC5D,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,mBAAmB,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,KAAsB,EACtB,IAAoB,EACpB,MAAc;IAEd,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACxB,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,eAAe,CAAC;IAC3D,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,MAAM,CAAC,iBAAiB,CAAC;IAC/D,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,MAAM,CAAC,gBAAgB,CAAC;AACjC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,KAAsB,EACtB,OAAgB,EAChB,IAAoB;IAEpB,MAAM,OAAO,GAAyB,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACrE,EAAE,EAAE,aAAa,OAAO,CAAC,KAAK,EAAE;QAChC,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,KAAK,EAAE,MAAM;KACd,CAAC,CAAC,CAAC;IACJ,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,CAAC,IAAI,CAAC;YACX,EAAE,EAAE,SAAS;YACb,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK;YAClC,KAAK,EAAE,mBAAmB;YAC1B,KAAK,EAAE,QAAQ;SAChB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,IAAkB;IAC5C,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;IAC7B,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,KAAK,IAAI,GAAG,CAAC;AAC9D,CAAC;AAED,SAAS,MAAM,CAAC,IAAY;IAC1B,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,OAAO,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC;AACnD,CAAC"}

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

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionVariablesView } from '../core/projectionOptions.ts';
+/** Which of the four views the run has the data to draw. */
+export interface ProjectionVariablesAvailability {
+    /** Whether the run reported the average sample and how far each component reaches. */
+    canShowEffect: boolean;
+    /** Whether the model divided each measurement by its own spread. */
+    canRescale: boolean;
+    /** Whether exactly one sample is selected. */
+    canPickSample: boolean;
+}
+/**
+ * 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 declare function projectionViewChoices(copy: ProjectionCopy, available: ProjectionVariablesAvailability): ReadonlyArray<OverlayOption<ProjectionVariablesView>>;
+//# sourceMappingURL=projectionViewChoices.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"projectionViewChoices.d.ts","sourceRoot":"","sources":["../../../src/projection/ui/projectionViewChoices.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAE5E,4DAA4D;AAC5D,MAAM,WAAW,+BAA+B;IAC9C,sFAAsF;IACtF,aAAa,EAAE,OAAO,CAAC;IACvB,oEAAoE;IACpE,UAAU,EAAE,OAAO,CAAC;IACpB,8CAA8C;IAC9C,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,+BAA+B,GACzC,aAAa,CAAC,aAAa,CAAC,uBAAuB,CAAC,CAAC,CAsBvD"}

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,187 @@
+/**
+ * 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';
+/** A sample the reader opened, and where they opened it. */
+export interface ProjectionSampleOpen {
+    /** Its name, from `samples.ids` — the currency every other callback uses. */
+    id: string;
+    /** Its row in the score matrix, for a caller that would rather index. */
+    index: number;
+    /** Where the reader clicked, in pixels from the figure's left edge. */
+    x: number;
+    /** Where they clicked, in pixels from its top edge. */
+    y: number;
+    /**
+     * Where they clicked in the window, which is what an editor floating over
+     * the page is anchored to.
+     */
+    clientX: number;
+    /** Where they clicked in the window. */
+    clientY: number;
+}
+/** 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;
+    /**
+     * Called when the reader double-clicks a sample, on the map or in the cloud.
+     *
+     * The viewer says what a sample *is*; this is the door to what the page
+     * around it can do with one — open its record, edit the class it was given,
+     * show the spectrum behind the dot. The viewer does nothing itself, so a
+     * page that does not pass it has a double click that only ever resets the
+     * frame.
+     *
+     * The sample is selected first, because a double click is also two clicks.
+     * Holding every single click for the double-click interval to avoid that
+     * would make the commonest gesture in the figure feel slow, which is a worse
+     * trade than a redundant selection on the rarest one.
+     * @default undefined
+     */
+    onSampleDoubleClick?: (sample: ProjectionSampleOpen) => 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":"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"}

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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"}