@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/ui/JexlFilterDialog.js

@@ -0,0 +1,167 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { use, useState } from 'react';
+import { getEnv } from '@jbrowse/mobx-state-tree';
+import AddIcon from '@mui/icons-material/Add';
+import { Button, ListItemText, MenuItem, Tab, Tabs, TextField, } from '@mui/material';
+import { observer } from 'mobx-react';
+import { readConfObject } from '../configuration/readConfObject.js';
+import { addRow, describedColumns, readFilterRows, removeRow, replaceRow, resolveFields, stripJexlPrefix, writeFilterRows, } from '../util/jexlFilterRows.js';
+import { activeJexlFilters } from '../util/jexlFilters.js';
+import { ensureJexlPrefix } from '../util/jexlStrings.js';
+import { getContainingTrack } from '../util/mstUtils.js';
+import { makeStyles } from '../util/tss-react/index.js';
+import ExternalLink from './ExternalLink.js';
+import { ConditionRowEditor, TextRowEditor, compileError, } from './JexlFilterRowEditors.js';
+import MonospaceTextField from './MonospaceTextField.js';
+import SubmitDialog from './SubmitDialog.js';
+/**
+ * What a display filtering plain annotation features offers as a starting
+ * point. A display whose features are a richer record — a VCF, say — passes its
+ * own list instead: the examples are the only place the dialog says what is
+ * readable off a feature, so a variant track showing `type=='gene'` is teaching
+ * the wrong vocabulary.
+ */
+const FEATURE_FILTER_EXAMPLES = [
+    {
+        code: "jexl:get(feature,'name')=='BRCA1'",
+        description: 'show only features where the name attribute is BRCA1',
+    },
+    {
+        code: "jexl:startsWith(get(feature,'name'),'PREFIX')",
+        description: "show only features where the string 'PREFIX' is the prefix of the feature name. endsWith also works",
+    },
+    {
+        code: "jexl:includes(get(feature,'name'),'PREFIX')",
+        description: "show only features where the string 'PREFIX' appears in the feature name",
+    },
+    {
+        code: "jexl:get(feature,'type')=='gene'",
+        description: 'show only gene type features in a GFF that has many other feature types',
+    },
+    {
+        code: "jexl:get(feature,'score') > 400",
+        description: 'show only features that have a score greater than 400',
+    },
+    {
+        code: "jexl:get(feature,'end') - get(feature,'start') < 1000000",
+        description: 'show only features with length less than 1Mbp',
+    },
+];
+const FEATURE_FIELDS = [
+    { label: 'name', path: ['name'], type: 'text' },
+    { label: 'type', path: ['type'], type: 'text' },
+    { label: 'score', path: ['score'], type: 'number' },
+    { label: 'start', path: ['start'], type: 'number' },
+    { label: 'end', path: ['end'], type: 'number' },
+    { label: 'strand', path: ['strand'], type: 'number' },
+];
+const useStyles = makeStyles()(theme => ({
+    body: {
+        minHeight: 280,
+    },
+    tabs: {
+        marginBottom: theme.spacing(2),
+    },
+    hint: {
+        marginBottom: theme.spacing(2),
+        color: theme.palette.text.secondary,
+    },
+    examples: {
+        minWidth: 220,
+        marginBottom: theme.spacing(1),
+    },
+}));
+function textLines(text) {
+    return text
+        .split('\n')
+        .map(line => line.trim())
+        .filter(line => !!line)
+        .map(ensureJexlPrefix);
+}
+function textError(text, jexl) {
+    for (const [i, line] of text.split('\n').entries()) {
+        const error = line.trim() ? compileError(line, jexl) : undefined;
+        if (error) {
+            return `Line ${i + 1}: ${error}`;
+        }
+    }
+    return undefined;
+}
+function trackName(model) {
+    try {
+        return readConfObject(getContainingTrack(model).configuration, 'name');
+    }
+    catch {
+        return undefined;
+    }
+}
+function withOneRow(state) {
+    return state.rows.length > 0 ? state : addRow(state);
+}
+/**
+ * Editor for a display's jexl feature filters, for any display implementing
+ * the two-tier {@link JexlFilterModel} contract. The Conditions tab shows each
+ * line as rows of field, operator and value where it can, and as text where it
+ * cannot; the Text tab is every line as text.
+ *
+ * `fields` lists what the field picker offers, then the columns `metadata`
+ * describes, if it is an adapter's `{column: description}` map. Either one
+ * given as a promise suspends the dialog until it resolves, so it must not
+ * reject.
+ */
+const JexlFilterDialog = observer(function JexlFilterDialog({ model, handleClose, examples = FEATURE_FILTER_EXAMPLES, fields = FEATURE_FIELDS, metadata, }) {
+    const { classes } = useStyles();
+    const jexl = getEnv(model).pluginManager
+        .jexl;
+    const fieldList = fields instanceof Promise ? use(fields) : fields;
+    const described = metadata && use(metadata);
+    const [choices] = useState(() => resolveFields([...fieldList, ...describedColumns(described, fieldList)]));
+    const [state, setState] = useState(() => withOneRow(readFilterRows(activeJexlFilters(model), jexl, choices)));
+    const [tab, setTab] = useState('conditions');
+    const [text, setText] = useState({ value: '', shown: '' });
+    const textEdited = text.value !== text.shown;
+    const error = tab === 'text'
+        ? textError(text.value, jexl)
+        : state.rows.some(row => row.kind === 'text' && compileError(row.text, jexl));
+    const name = trackName(model);
+    return (_jsx(SubmitDialog, { maxWidth: "md", fullWidth: true, open: true, title: name ? `Filter ${name}` : 'Filter features', submitText: "Apply", submitDisabled: !!error, onCancel: handleClose, onSubmit: () => {
+            // An emptied list is "show everything", which is NOT the same as
+            // following the config slot, so it is set as an override too
+            model.setFilter(tab === 'text' && textEdited
+                ? textLines(text.value)
+                : writeFilterRows(state));
+            handleClose();
+        }, children: _jsxs("div", { className: classes.body, children: [_jsxs(Tabs, { className: classes.tabs, value: tab, onChange: (_, next) => {
+                        if (next === 'text') {
+                            const value = writeFilterRows(state)
+                                .map(stripJexlPrefix)
+                                .join('\n');
+                            setText({ value, shown: value });
+                        }
+                        else if (textEdited) {
+                            setState(withOneRow(readFilterRows(textLines(text.value), jexl, choices)));
+                        }
+                        setTab(next);
+                    }, children: [_jsx(Tab, { value: "conditions", label: "Conditions" }), _jsx(Tab, { value: "text", label: "Text", "data-testid": "jexl-filter-text-tab" })] }), tab === 'conditions' ? (_jsxs(_Fragment, { children: [_jsx("div", { className: classes.hint, children: "Show features that match every condition." }), state.rows.map(row => row.kind === 'text' ? (_jsx(TextRowEditor, { row: row, jexl: jexl, onChange: next => {
+                                setState(replaceRow(state, next));
+                            }, onRemove: () => {
+                                setState(removeRow(state, row.id));
+                            } }, row.id)) : (_jsx(ConditionRowEditor, { row: row, choices: choices, onChange: next => {
+                                setState(replaceRow(state, next));
+                            }, onRemove: () => {
+                                setState(removeRow(state, row.id));
+                            } }, row.id))), _jsx(Button, { startIcon: _jsx(AddIcon, {}), onClick: () => {
+                                setState(addRow(state));
+                            }, children: "Add condition" })] })) : (_jsxs(_Fragment, { children: [_jsx(TextField, { select: true, size: "small", label: "Insert example\u2026", value: "", className: classes.examples, onChange: event => {
+                                const code = stripJexlPrefix(event.target.value);
+                                setText({
+                                    ...text,
+                                    value: text.value.trim()
+                                        ? `${text.value.trimEnd()}\n${code}`
+                                        : code,
+                                });
+                            }, children: examples.map(({ code, description }) => (_jsx(MenuItem, { value: code, children: _jsx(ListItemText, { primary: stripJexlPrefix(code), secondary: description }) }, code))) }), _jsx(MonospaceTextField, { fullWidth: true, minRows: 6, maxRows: 14, value: text.value, error: error, helperText: "One filter per line; a feature has to pass every line.", onChange: value => {
+                                setText({ ...text, value });
+                            } }), _jsxs("p", { children: ["See the", ' ', _jsx(ExternalLink, { href: "https://jbrowse.org/jb2/docs/config_guides/jexl/", children: "jexl documentation" }), ' ', "for the expression language."] })] }))] }) }));
+});
+export default JexlFilterDialog;

package/esm/ui/JexlFilterRowEditors.d.ts

@@ -0,0 +1,15 @@
+import type { ConditionRow, FieldChoice, TextRow } from '../util/jexlFilterRows.ts';
+import type { Jexl } from '@jbrowse/jexl';
+export declare function compileError(line: string, jexl: Pick<Jexl, 'compile'>): string | undefined;
+export declare function ConditionRowEditor({ row, choices, onChange, onRemove, }: {
+    row: ConditionRow;
+    choices: FieldChoice[];
+    onChange: (row: ConditionRow) => void;
+    onRemove: () => void;
+}): import("react").JSX.Element;
+export declare function TextRowEditor({ row, jexl, onChange, onRemove, }: {
+    row: TextRow;
+    jexl: Pick<Jexl, 'compile'>;
+    onChange: (row: TextRow) => void;
+    onRemove: () => void;
+}): import("react").JSX.Element;

package/esm/ui/JexlFilterRowEditors.js

@@ -0,0 +1,90 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import CloseIcon from '@mui/icons-material/Close';
+import { Autocomplete, IconButton, ListItemText, MenuItem, TextField, } from '@mui/material';
+import { OPERATORS, stripJexlPrefix, typedField, withField, withOp, } from '../util/jexlFilterRows.js';
+import { makeStyles } from '../util/tss-react/index.js';
+import MonospaceTextField from './MonospaceTextField.js';
+const useStyles = makeStyles()(theme => ({
+    row: {
+        display: 'flex',
+        alignItems: 'flex-start',
+        gap: theme.spacing(1),
+        marginBottom: theme.spacing(1),
+    },
+    field: {
+        width: 220,
+        flexShrink: 0,
+    },
+    op: {
+        width: 130,
+        flexShrink: 0,
+    },
+    value: {
+        flex: 1,
+    },
+    expression: {
+        width: 24,
+        flexShrink: 0,
+        textAlign: 'center',
+        fontStyle: 'italic',
+        fontFamily: 'serif',
+        fontSize: 18,
+        paddingTop: 6,
+        color: theme.palette.text.secondary,
+    },
+}));
+export function compileError(line, jexl) {
+    try {
+        jexl.compile(stripJexlPrefix(line.trim()));
+        return undefined;
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+}
+function RemoveButton({ onClick }) {
+    return (_jsx(IconButton, { size: "small", "aria-label": "Remove condition", onClick: onClick, children: _jsx(CloseIcon, { fontSize: "small" }) }));
+}
+function ValueInput({ row, onChange, }) {
+    const { classes } = useStyles();
+    const { field, op, value } = row;
+    if (op === 'set' || op === '!set') {
+        return _jsx("div", { className: classes.value });
+    }
+    const suggestions = field?.values ?? [];
+    if (op === 'in') {
+        return (_jsx(Autocomplete, { className: classes.value, size: "small", multiple: true, freeSolo: true, autoSelect: true, options: suggestions, value: [value].flat(), onChange: (_, next) => {
+                onChange({ ...row, value: next });
+            }, renderInput: params => (_jsx(TextField, { ...params, placeholder: "Values, Enter after each" })) }));
+    }
+    const text = [value].flat()[0] ?? '';
+    return suggestions.length > 0 && op !== '~' ? (_jsx(Autocomplete, { className: classes.value, size: "small", freeSolo: true, options: suggestions, inputValue: text, onInputChange: (_, next) => {
+            onChange({ ...row, value: next });
+        }, renderInput: params => _jsx(TextField, { ...params, placeholder: "Value" }) })) : (_jsx(TextField, { className: classes.value, size: "small", placeholder: op === '~' ? 'Regular expression' : 'Value', type: field?.type === 'number' ? 'number' : 'text', disabled: !field, value: text, onChange: event => {
+            onChange({ ...row, value: event.target.value });
+        } }));
+}
+export function ConditionRowEditor({ row, choices, onChange, onRemove, }) {
+    const { classes } = useStyles();
+    const { field } = row;
+    const grouped = choices.some(choice => choice.group);
+    return (_jsxs("div", { className: classes.row, children: [_jsx(Autocomplete, { className: classes.field, size: "small", freeSolo: true, autoSelect: true, options: choices, groupBy: grouped ? choice => choice.group ?? '' : undefined, getOptionLabel: choice => typeof choice === 'string' ? choice : choice.label, getOptionKey: choice => typeof choice === 'string' ? choice : choice.key, isOptionEqualToValue: (a, b) => typeof b !== 'string' && a.key === b.key, value: field ?? null, onChange: (_, next) => {
+                    const chosen = typeof next !== 'string'
+                        ? next
+                        : next === field?.label
+                            ? field
+                            : (choices.find(choice => choice.label === next) ??
+                                typedField(next));
+                    if (chosen && chosen.key !== field?.key) {
+                        onChange(withField(row, chosen));
+                    }
+                }, renderOption: ({ key, ...props }, choice) => (_jsx("li", { ...props, children: _jsx(ListItemText, { primary: choice.label, secondary: choice.description }) }, key)), renderInput: params => _jsx(TextField, { ...params, placeholder: "Field" }) }), _jsx(TextField, { className: classes.op, select: true, size: "small", disabled: !field, value: row.op, helperText: field?.multi ? 'any value' : undefined, onChange: event => {
+                    onChange(withOp(row, event.target.value));
+                }, children: OPERATORS[field?.type ?? 'any'].map(({ op, label }) => (_jsx(MenuItem, { value: op, children: label }, op))) }), _jsx(ValueInput, { row: row, onChange: onChange }), _jsx(RemoveButton, { onClick: onRemove })] }));
+}
+export function TextRowEditor({ row, jexl, onChange, onRemove, }) {
+    const { classes } = useStyles();
+    return (_jsxs("div", { className: classes.row, children: [_jsx("div", { className: classes.expression, title: "An expression the field pickers cannot show", children: "\u0192" }), _jsx(MonospaceTextField, { className: classes.value, variant: "standard", fullWidth: true, value: row.text, error: compileError(row.text, jexl), onChange: text => {
+                    onChange({ ...row, text });
+                } }), _jsx(RemoveButton, { onClick: onRemove })] }));
+}

package/esm/ui/LabeledCheckbox.d.ts

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+export default function LabeledCheckbox({ checked, onChange, label, className, disabled, size, }: {
+    checked: boolean;
+    onChange: (checked: boolean) => void;
+    label: ReactNode;
+    className?: string;
+    disabled?: boolean;
+    size?: 'small' | 'medium';
+}): import("react").JSX.Element;

package/esm/ui/LabeledCheckbox.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Checkbox, FormControlLabel } from '@mui/material';
+export default function LabeledCheckbox({ checked, onChange, label, className, disabled, size, }) {
+    return (_jsx(FormControlLabel, { className: className, disabled: disabled, control: _jsx(Checkbox, { size: size, checked: checked, onChange: event => {
+                onChange(event.target.checked);
+            } }), label: label }));
+}

package/esm/ui/LazyBaseTooltip.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentProps } from 'react';
+declare const Lazy: import("react").LazyExoticComponent<typeof import("./BaseTooltip.tsx").default>;
+export default function LazyBaseTooltip(props: ComponentProps<typeof Lazy>): import("react").JSX.Element;
+export {};

package/esm/ui/LazyBaseTooltip.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Suspense, lazy } from 'react';
+// The tooltip, behind its own chunk: @floating-ui is ~266KB and this is what
+// lets the ui barrel export it without putting that on the startup path. A
+// consumer that wants the eager component deep-imports './BaseTooltip.tsx'.
+const Lazy = lazy(() => import('./BaseTooltip.js'));
+export default function LazyBaseTooltip(props) {
+    return (_jsx(Suspense, { fallback: null, children: _jsx(Lazy, { ...props }) }));
+}

package/esm/ui/LegendSwatchGlyph.d.ts

@@ -0,0 +1,7 @@
+import type { LegendSwatch } from './legendSpec.ts';
+export declare function LegendSwatchGlyph({ swatch, size, x, y, }: {
+    swatch: LegendSwatch;
+    size: number;
+    x?: number;
+    y?: number;
+}): import("react").JSX.Element;

package/esm/ui/LegendSwatchGlyph.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { appendGlyph } from '@jbrowse/render-core/marks/glyphPaint';
+import { DIAMOND_GLYPH_SCALE } from '@jbrowse/render-core/shaders/pointMarkConsts';
+import { SHAPE_CODES } from '../util/shapeNames.js';
+// The point mark's own painter, recorded as SVG path data, so the key draws
+// the glyph the plot draws. The diamond paints wider than its diameter and
+// is scaled down to fit the box.
+function glyphPathData(shape, size, x, y) {
+    const d = [];
+    const path = {
+        moveTo: (px, py) => d.push(`M${px} ${py}`),
+        lineTo: (px, py) => d.push(`L${px} ${py}`),
+        closePath: () => d.push('Z'),
+        rect: (px, py, w, h) => d.push(`M${px} ${py}h${w}v${h}h${-w}Z`),
+        arc: (cx, cy, r) => d.push(`A${r} ${r} 0 1 0 ${cx - r} ${cy}A${r} ${r} 0 1 0 ${cx + r} ${cy}Z`),
+    };
+    const diameter = shape === 'diamond' ? size / DIAMOND_GLYPH_SCALE : size;
+    appendGlyph(path, SHAPE_CODES[shape], x + size / 2, y + size / 2, diameter);
+    return d.join('');
+}
+// The one place that decides what a legend swatch looks like. Returns a bare
+// shape rather than a rooted <svg>, so the floating legend (which wraps it in an
+// inline <svg>) and the SVG export (which drops it into a row <g>) draw the
+// identical box.
+//
+// The shape fills the `size` box from (x, y) so a caller can lay swatches out on
+// a fixed pitch.
+export function LegendSwatchGlyph({ swatch, size, x = 0, y = 0, }) {
+    return swatch.shape ? (_jsx("path", { d: glyphPathData(swatch.shape, size, x, y), fill: swatch.color })) : (_jsx("rect", { x: x, y: y, width: size, height: size, fill: swatch.color }));
+}

package/esm/ui/LoadingDots.d.ts

@@ -0,0 +1 @@
+export default function LoadingDots(): import("react").JSX.Element;

package/esm/ui/LoadingDots.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { makeStyles } from '../util/tss-react/index.js';
+import { dot1, dot2, dot3 } from './loadingDotKeyframes.js';
+const useStyles = makeStyles()({
+    dots: {
+        display: 'inline-block',
+        width: '1em',
+        textAlign: 'left',
+        '& span': {
+            display: 'inline-block',
+            opacity: 0,
+            // promote each dot to its own compositor layer so the opacity animation
+            // is offloaded from the main thread and keeps running during jank
+            willChange: 'opacity',
+            '&:nth-of-type(1)': {
+                animation: `${dot1} 1.2s infinite`,
+            },
+            '&:nth-of-type(2)': {
+                animation: `${dot2} 1.2s infinite`,
+            },
+            '&:nth-of-type(3)': {
+                animation: `${dot3} 1.2s infinite`,
+            },
+        },
+    },
+});
+export default function LoadingDots() {
+    const { classes } = useStyles();
+    return (_jsxs("span", { className: classes.dots, children: [_jsx("span", { children: "." }), _jsx("span", { children: "." }), _jsx("span", { children: "." })] }));
+}

package/esm/ui/LoadingEllipses.d.ts

@@ -3,5 +3,21 @@ interface Props extends TypographyProps {
     message?: string;
     children?: never;
 }
-export default function LoadingEllipses({ message, children, variant, ...rest }: Props): import("react/jsx-runtime").JSX.Element;
+/**
+ * The label every part of the app shows while it is working, and — through
+ * `data-busy` — the only thing an automated capture has to look at to know that
+ * it is.
+ *
+ * The attribute is the contract that replaces reading the label. A harness
+ * waiting for a page to finish used to scan visible text for /^loading/ and
+ * resolve `getComputedStyle` to decide whether each match was on screen, which
+ * makes a rendering detail load-bearing: a reworded message, a translation, or
+ * an element that animates its opacity all change the answer. `[data-busy]` is
+ * published by the component that knows, so a wait is one selector.
+ *
+ * Anything that renders its own in-flight banner instead of this component
+ * should carry the attribute too — see `isPageBusyInPage` in
+ * `@jbrowse/capture`, which is what reads it.
+ */
+export default function LoadingEllipses({ message, variant, ...rest }: Props): import("react").JSX.Element;
 export {};

package/esm/ui/LoadingEllipses.js

@@ -1,31 +1,22 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Typography } from '@mui/material';
-import { cx, keyframes, makeStyles } from "../util/tss-react/index.js";
-const useStyles = makeStyles()({
-    dots: {
-        '&::after': {
-            display: 'inline-block',
-            content: '""',
-            width: '1em',
-            textAlign: 'left',
-            animation: `${keyframes `
-      0% {
-        content: '';
-      }
-      25% {
-          content: '.';
-      }
-      50% {
-        content: '..';
-      }
-      75% {
-        content: '...';
-      }
-      `} 1.2s infinite ease-in-out`,
-        },
-    },
-});
-export default function LoadingEllipses({ message, children, variant = 'body2', ...rest }) {
-    const { classes } = useStyles();
-    return (_jsx(Typography, { className: cx(classes.dots, rest.className), ...rest, variant: variant, children: message || 'Loading' }));
+import LoadingDots from './LoadingDots.js';
+/**
+ * The label every part of the app shows while it is working, and — through
+ * `data-busy` — the only thing an automated capture has to look at to know that
+ * it is.
+ *
+ * The attribute is the contract that replaces reading the label. A harness
+ * waiting for a page to finish used to scan visible text for /^loading/ and
+ * resolve `getComputedStyle` to decide whether each match was on screen, which
+ * makes a rendering detail load-bearing: a reworded message, a translation, or
+ * an element that animates its opacity all change the answer. `[data-busy]` is
+ * published by the component that knows, so a wait is one selector.
+ *
+ * Anything that renders its own in-flight banner instead of this component
+ * should carry the attribute too — see `isPageBusyInPage` in
+ * `@jbrowse/capture`, which is what reads it.
+ */
+export default function LoadingEllipses({ message, variant = 'body2', ...rest }) {
+    return (_jsxs(Typography, { ...rest, variant: variant, "data-busy": "true", children: [message || 'Loading', _jsx(LoadingDots, {})] }));
 }

package/esm/ui/LoadingOverlay.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns false, then flips true once `active` has stayed true continuously for
+ * `delayMs`. Each activation gets a fresh delay, and the flag drops the moment
+ * `active` does.
+ *
+ * Keyed on a count of RISING edges rather than on `active` itself, so the
+ * falling edge does no work at all. A display refetching through a wheel zoom
+ * flips `active` several times a second — it finishes a fetch, waits out the
+ * debounce, starts the next — and an effect depending on `active` tore its timer
+ * down and built a new one on each of those, twice over, for a scrim that by
+ * construction never appears. Deriving the flag from a comparison instead means
+ * one `setTimeout` per loading pulse, which is the floor for these semantics.
+ */
+export declare function useDelayedFlag(active: boolean, delayMs: number): boolean;
+export default function LoadingOverlay({ statusMessage, progress, isVisible, immediate, canceled, onCancel, onRetry, }: {
+    statusMessage?: string;
+    progress?: number;
+    isVisible?: boolean;
+    immediate?: boolean;
+    canceled?: boolean;
+    onCancel?: () => void;
+    onRetry?: () => void;
+}): import("react").JSX.Element | null;

package/esm/ui/LoadingOverlay.js

@@ -0,0 +1,139 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import CloseIcon from '@mui/icons-material/Close';
+import RefreshIcon from '@mui/icons-material/Refresh';
+import { IconButton, Tooltip } from '@mui/material';
+import { progressLabel } from '../util/progress.js';
+import { makeStyles } from '../util/tss-react/index.js';
+import LoadingDots from './LoadingDots.js';
+import StatusProgressBar from './StatusProgressBar.js';
+import { alpha } from './palette.js';
+const cancelDelayMs = 5000;
+// suppress the overlay for the first moments of a refetch so quick zoom/pan
+// loads stay silent and only genuinely slow loads ever draw the indicator.
+// Skipped when `immediate` is set (initial load with nothing on screen yet) —
+// there's no content to flash over, so the indicator shows right away.
+const flashDelayMs = 250;
+/**
+ * Returns false, then flips true once `active` has stayed true continuously for
+ * `delayMs`. Each activation gets a fresh delay, and the flag drops the moment
+ * `active` does.
+ *
+ * Keyed on a count of RISING edges rather than on `active` itself, so the
+ * falling edge does no work at all. A display refetching through a wheel zoom
+ * flips `active` several times a second — it finishes a fetch, waits out the
+ * debounce, starts the next — and an effect depending on `active` tore its timer
+ * down and built a new one on each of those, twice over, for a scrim that by
+ * construction never appears. Deriving the flag from a comparison instead means
+ * one `setTimeout` per loading pulse, which is the floor for these semantics.
+ */
+export function useDelayedFlag(active, delayMs) {
+    const [previous, setPrevious] = useState(active);
+    const [activation, setActivation] = useState(0);
+    if (previous !== active) {
+        setPrevious(active);
+        if (active) {
+            setActivation(n => n + 1);
+        }
+    }
+    const [elapsedFor, setElapsedFor] = useState(-1);
+    useEffect(() => {
+        const id = setTimeout(() => {
+            setElapsedFor(activation);
+        }, delayMs);
+        return () => {
+            clearTimeout(id);
+        };
+    }, [activation, delayMs]);
+    return active && elapsedFor === activation;
+}
+const useStyles = makeStyles()(theme => {
+    // derive the stripe + chip tints from the theme so the "something's happening"
+    // signal stays subtle and equally visible in light and dark mode
+    const stripe = alpha(theme.palette.text.primary, 0.05);
+    return {
+        overlay: {
+            position: 'absolute',
+            top: 0,
+            left: 0,
+            right: 0,
+            bottom: 0,
+            background: `repeating-linear-gradient(45deg, transparent, transparent 8px, ${stripe} 8px, ${stripe} 16px)`,
+            pointerEvents: 'none',
+            zIndex: 1,
+            display: 'flex',
+            justifyContent: 'center',
+            alignItems: 'flex-start',
+            paddingTop: '20px',
+        },
+        // the status chip is the only interactive element; the striped backdrop stays
+        // click-through so it never swallows track interactions.
+        //
+        // Mostly-opaque paper (was 0.4, which let dense features and the striping
+        // read straight through the label): the chip sits over a canvas whose colors
+        // aren't known here, so the text needs its own backing to stay legible.
+        // `background.paper` rather than a literal white so dark mode gets the dark
+        // equivalent, and short of fully opaque so it still reads as an overlay.
+        content: {
+            pointerEvents: 'auto',
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            gap: 2,
+            background: alpha(theme.palette.background.paper, 0.85),
+            borderRadius: 4,
+            padding: '2px 8px',
+        },
+        row: {
+            display: 'flex',
+            alignItems: 'center',
+            gap: 4,
+        },
+        text: {
+            fontSize: '0.8rem',
+            fontWeight: 300,
+        },
+        bar: {
+            width: 160,
+        },
+    };
+});
+export default function LoadingOverlay({ statusMessage, progress, isVisible, immediate, canceled, onCancel, onRetry, }) {
+    const { classes } = useStyles();
+    const hasProgress = progress !== undefined;
+    // anti-flash: only render after the load has run long enough to be worth
+    // signaling, so fast loads show nothing at all. `immediate` bypasses this for
+    // initial loads, where nothing is on screen to flash over yet.
+    //
+    // The delay runs off `isVisible` ALONE. Feeding `!immediate` in as well made
+    // `immediate` *restart* the timer rather than merely bypass it, and the chrome
+    // flips `immediate` mid-load: it passes `immediate={!painted}`, so first paint
+    // drops it while the phase is still `loading` — region 1 drawn, regions 2..n
+    // in flight. The scrim then blinked out for a fresh 250 ms in the middle of
+    // one continuous load.
+    const shownAfterDelay = useDelayedFlag(!!isVisible, flashDelayMs);
+    const shown = !!isVisible && (!!immediate || shownAfterDelay);
+    // only offer cancel after the overlay has been continuously visible for a few
+    // seconds, so a quick load can't be canceled by an accidental click.
+    //
+    // Keyed on `shown` rather than `isVisible`, which is what "continuously
+    // visible" means and is also what keeps this timer out of a zoom: a display
+    // refetching per animation frame flips `isVisible` a couple of times a frame,
+    // and each flip was a clearTimeout/setTimeout pair for a five-second delay
+    // that could never elapse — 368 timer installs over a ten-second gesture,
+    // half of them these.
+    const cancelableAfterDelay = useDelayedFlag(shown, cancelDelayMs);
+    const cancelable = shown && cancelableAfterDelay;
+    // Rendered only while shown. The content chip is `pointerEvents:auto`, so
+    // leaving it mounted (merely transparent) in the idle state would silently
+    // swallow clicks/hovers over the top-center of every track it overlays. There
+    // is no fade transition, so mount/unmount is visually identical to toggling
+    // opacity anyway.
+    // `loading-overlay` is a readiness selector meaning work in flight, so the
+    // canceled state, which is finished, publishes its own
+    return shown ? (_jsx("span", { className: classes.overlay, "data-testid": canceled ? 'loading-overlay-canceled' : 'loading-overlay', children: _jsx("span", { className: classes.content, children: canceled ? (_jsxs("span", { className: classes.row, children: [_jsx("span", { className: classes.text, children: "Loading canceled" }), onRetry ? (_jsx(Tooltip, { title: "Retry", children: _jsx(IconButton, { size: "small", "data-testid": "loading-overlay-retry", onClick: () => {
+                                onRetry();
+                            }, children: _jsx(RefreshIcon, { fontSize: "inherit" }) }) })) : null] })) : (_jsxs(_Fragment, { children: [_jsxs("span", { className: classes.row, children: [_jsxs("span", { className: classes.text, children: [progressLabel(statusMessage || 'Loading', progress), hasProgress ? null : _jsx(LoadingDots, {})] }), onCancel && cancelable ? (_jsx(Tooltip, { title: "Cancel", children: _jsx(IconButton, { size: "small", "data-testid": "loading-overlay-cancel", onClick: () => {
+                                        onCancel();
+                                    }, children: _jsx(CloseIcon, { fontSize: "inherit" }) }) })) : null] }), hasProgress ? (_jsx(StatusProgressBar, { className: classes.bar, fraction: progress })) : null] })) }) })) : null;
+}

package/esm/ui/LoadingProgress.d.ts

@@ -0,0 +1,16 @@
+import type { TypographyProps } from '@mui/material';
+/**
+ * The shared "labelled ellipses + optional determinate bar" body used by the
+ * loading/refetch indicators. Renders a {@link LoadingEllipses} label — with the
+ * rounded percent appended via {@link progressLabel} when `fraction` is
+ * determinate — and a determinate {@link StatusProgressBar} only when a
+ * `fraction` is present (an indeterminate phase shows just the animated label,
+ * no bar). Callers own the surrounding layout and supply `barClassName` for the
+ * bar width.
+ */
+export default function LoadingProgress({ message, fraction, variant, barClassName, }: {
+    message?: string;
+    fraction?: number;
+    variant?: TypographyProps['variant'];
+    barClassName?: string;
+}): import("react").JSX.Element;