@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/ui/ViewLoadingScreen.js

@@ -0,0 +1,76 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Typography } from '@mui/material';
+import { makeStyles } from '../util/tss-react/index.js';
+import LoadingProgress from './LoadingProgress.js';
+// Long enough that a load which is merely slow never says it, short enough to
+// beat the point where someone decides the app is broken. Every status write
+// resets it, so a download that is still moving its bar never reaches it
+const STALL_MS = 5000;
+const useStyles = makeStyles()(theme => ({
+    root: {
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: 8,
+        padding: 20,
+    },
+    bar: {
+        width: 300,
+        maxWidth: '80%',
+    },
+    stalled: {
+        maxWidth: 500,
+        textAlign: 'center',
+        // a presigned URL is a few hundred unbroken characters, and the notice must
+        // not widen the view it is centered in
+        overflowWrap: 'anywhere',
+        color: theme.palette.text.secondary,
+    },
+}));
+/**
+ * Has this load said the same thing for {@link STALL_MS}? `key` is everything
+ * the screen is showing, so any status at all — a new phase, another chunk of
+ * bytes — restarts the wait, and only a load that has genuinely stopped saying
+ * anything gets there.
+ *
+ * The timeout stores the key it fired for rather than a boolean, which is what
+ * makes the reset free: a key that has moved on is not the key that was stalled,
+ * so the notice goes away on the next status without a write to undo it.
+ */
+function useStalled(key) {
+    const [stalledKey, setStalledKey] = useState();
+    useEffect(() => {
+        const timer = setTimeout(() => {
+            setStalledKey(key);
+        }, STALL_MS);
+        return () => {
+            clearTimeout(timer);
+        };
+    }, [key]);
+    return stalledKey === key;
+}
+/**
+ * The "view exists but isn't ready yet" screen a view renders instead of its
+ * content — LGV, dotplot and linear synteny all show it while the assembly they
+ * name is still loading, labelled with which of the assembly's files is
+ * downloading and a determinate bar when that download reports one.
+ *
+ * A load that then stops reporting names the file it is waiting on. The phase
+ * label alone does not: "Downloading chromosome aliases" is a fair description
+ * of what is happening and no help at all in front of a hub that has stopped
+ * answering, where the one useful fact is which server that is. Shown only once
+ * the load has actually stalled, so a healthy startup never sees a URL.
+ *
+ * Metrics deliberately match `DiagonalizeLoadingScreen`, which is the sibling
+ * render branch in both comparative views: a view that flipped between the two
+ * would otherwise jump between two differently laid-out loading screens. That
+ * shared layout is also why this exists at all rather than each view calling
+ * {@link LoadingProgress} directly — bare, it renders an unconstrained
+ * full-width bar under an unaligned label.
+ */
+export default function ViewLoadingScreen({ message, fraction, source, }) {
+    const { classes } = useStyles();
+    const stalled = useStalled(`${message}|${fraction}|${source}`);
+    return (_jsxs("div", { className: classes.root, children: [_jsx(LoadingProgress, { variant: "h6", message: message, fraction: fraction, barClassName: classes.bar }), stalled && source ? (_jsxs(Typography, { variant: "body2", className: classes.stalled, children: ["still waiting on ", source] })) : null] }));
+}

package/esm/ui/addExtensionElement.d.ts

@@ -0,0 +1,18 @@
+import type PluginManager from '../PluginManager.ts';
+import type { ExtensionPointProps, PointsOfKind } from '../PluginManager.ts';
+import type { ComponentType } from 'react';
+/**
+ * The extension points that accumulate an array of rendered elements — every
+ * point declared `ElementList`, the LGV and dotplot overlays.
+ * {@link PluggableElements} is the producer side.
+ */
+export type ElementExtensionPointName = PointsOfKind<'elementList'>;
+/**
+ * Render `component` into an overlay extension point, passing it the point's
+ * props.
+ *
+ * Prefer this to contributing the element yourself: it fixes the React `key` at
+ * registration time, and forgetting that one produces a warning pointing at
+ * framework code rather than at the plugin.
+ */
+export declare function addExtensionElement<N extends ElementExtensionPointName>(pluginManager: PluginManager, name: N, component: ComponentType<ExtensionPointProps<N>>): void;

package/esm/ui/addExtensionElement.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Render `component` into an overlay extension point, passing it the point's
+ * props.
+ *
+ * Prefer this to contributing the element yourself: it fixes the React `key` at
+ * registration time, and forgetting that one produces a warning pointing at
+ * framework code rather than at the plugin.
+ */
+export function addExtensionElement(pluginManager, name, component) {
+    const Component = component;
+    // unique per registration, and stable across renders because it is fixed at
+    // registration time rather than derived from anything the fold sees
+    const key = `${name}-${Component.displayName ?? Component.name}-${pluginManager.extensionPoints.get(name)?.length ?? 0}`;
+    // ElementExtensionPointName constrains this point's entry to a ReactNode, but
+    // neither compiler resolves ExtensionPointEntry<N> through the generic key.
+    // tsc7 rejects the element without the assertion; eslint's TS6 service thinks
+    // the assertion is redundant. Same split as SessionTracks.ts.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- tsc7 needs it
+    /* oxlint-disable typescript/no-unnecessary-type-assertion */
+    pluginManager.contributeToExtensionPoint(name, props => (_jsx(Component, { ...props }, key)));
+    /* oxlint-enable typescript/no-unnecessary-type-assertion */
+}

package/esm/ui/buildExtraTrackMenuItems.d.ts

@@ -0,0 +1,22 @@
+import type PluginManager from '../PluginManager.ts';
+import type { AnyConfigurationModel } from '../configuration/index.ts';
+import type { AbstractSessionModel, TrackActionView } from '../util/types/index.ts';
+import type { MenuItem } from './MenuTypes.ts';
+export interface ExtraTrackMenuItemsProps {
+    session: AbstractSessionModel;
+    config: AnyConfigurationModel;
+    view?: TrackActionView;
+}
+/** Return the items to add, or nothing when the track isn't yours. */
+export type ExtraTrackMenuItemsCallback = (props: ExtraTrackMenuItemsProps) => MenuItem | MenuItem[] | undefined;
+declare module '@jbrowse/core/PluginManager' {
+    interface ExtensionPointRegistry {
+        'Core-extraTrackMenuItems': {
+            args: MenuItem[];
+            result: MenuItem[];
+            props: ExtraTrackMenuItemsProps;
+        };
+    }
+}
+export declare function addExtraTrackMenuItems(pluginManager: PluginManager, callback: ExtraTrackMenuItemsCallback): void;
+export declare function buildExtraTrackMenuItems(pluginManager: PluginManager, props: ExtraTrackMenuItemsProps): MenuItem[];

package/esm/ui/buildExtraTrackMenuItems.js

@@ -0,0 +1,14 @@
+// Plugins call this to contribute per-track menu items (keyed off the track
+// config) to the hierarchical track selector. Wrapping the registration here
+// keeps the typed callback contract in one place so callers don't depend on the
+// extension-point type augmentation crossing package boundaries.
+export function addExtraTrackMenuItems(pluginManager, callback) {
+    pluginManager.contributeToExtensionPoint('Core-extraTrackMenuItems', callback);
+}
+// Returns the contributed per-track menu items, or an empty array when no
+// plugin contributes, so callers can spread it.
+export function buildExtraTrackMenuItems(pluginManager, props) {
+    return pluginManager.evaluateExtensionPoint(
+    /** #extensionPoint Core-extraTrackMenuItems | sync | Add items to a single track's menu */
+    'Core-extraTrackMenuItems', [], props);
+}

package/esm/ui/colorSwatchStyle.d.ts

@@ -0,0 +1,9 @@
+export declare const swatchStyle: {
+    readonly width: 24;
+    readonly height: 24;
+    readonly margin: 4;
+    readonly border: 'none';
+    readonly padding: 0;
+    readonly cursor: 'pointer';
+    readonly outline: 'none';
+};

package/esm/ui/colorSwatchStyle.js

@@ -0,0 +1,11 @@
+// Shared clickable color-swatch button style, used by ColorPicker's preset grid
+// and PopoverPicker's trigger swatch.
+export const swatchStyle = {
+    width: 24,
+    height: 24,
+    margin: 4,
+    border: 'none',
+    padding: 0,
+    cursor: 'pointer',
+    outline: 'none',
+};

package/esm/ui/colors.d.ts

@@ -1,10 +1,63 @@
 declare const category10: string[];
-declare const dark2: string[];
 declare const set1: string[];
-declare const set2: string[];
-declare const tableau10: string[];
-declare const ggplot2Colors6: string[];
-declare const ggplot2Colors5: string[];
-declare const ggplot2Colors4: string[];
-declare const ggplot2Colors3: string[];
-export { category10, dark2, ggplot2Colors3, ggplot2Colors4, ggplot2Colors5, ggplot2Colors6, set1, set2, tableau10, };
+export declare const paletteColors: {
+    category10: string[];
+    dark2: string[];
+    ggplot2Colors3: string[];
+    ggplot2Colors4: string[];
+    ggplot2Colors5: string[];
+    ggplot2Colors6: string[];
+    set1: string[];
+    set2: string[];
+    tableau10: string[];
+};
+/**
+ * The wide qualitative palette: every scheme above, in order, deduped and with
+ * the neutrals dropped. ~40 entries.
+ *
+ * One list, because "give each row a distinct color" is one question this repo
+ * answers in two places — the multi-row painter handing colors out by row
+ * index, and the arrangement dialog's palette-by-attribute — and two lists
+ * would mean a track's automatic colors and the colors it takes when a user
+ * palettes it by hand were different palettes for no reason a reader could see.
+ *
+ * `tableau10` leads because its hues are the most evenly separated, so a track
+ * with a handful of rows spends only that. The tail is what makes the 26
+ * 1000-Genomes population codes, or a repeat painting's classes, all get a
+ * curated color instead of falling out to `randomColor`.
+ *
+ * Past the end is the caller's problem, and the two callers answer differently
+ * on purpose: an attribute palette-by hashes the VALUE (stable across
+ * re-palettes), while a by-position painter has no value to hash and wraps.
+ */
+export declare const categoricalPalette: string[];
+/**
+ * Deterministic non-negative 32-bit hash of a string.
+ */
+export declare function hashString(str: string): number;
+/**
+ * Stable category10 color for a sequence name, via `hashString`.
+ *
+ * Kept as a published export; in-tree, prefer {@link refNameColor}, which hands
+ * the palette out by position where the caller knows the assembly's chromosome
+ * order and only hashes where it does not.
+ */
+export declare function getQueryColor(queryName: string): string;
+/** The palette color for a chromosome at `position` in its assembly. */
+export declare function refNamePaletteColorAt(position: number): string;
+/**
+ * The color a refName paints, BY POSITION IN THE ASSEMBLY where the caller
+ * knows its chromosome order.
+ *
+ * Handing the palette out rather than hashing into it is what stops a genome
+ * painting two of its own chromosomes the same color: nine slots means ten or
+ * more chromosomes re-use one, and by the birthday bound long before that. On
+ * hg38 the hash puts chr1, chr12, chr21 and chrY on one color.
+ *
+ * `position` is undefined for the case the order genuinely is not available —
+ * an assembly still loading, or a refName the assembly does not list (a
+ * scaffold under an alias). There a stable arbitrary color beats no color, so
+ * it falls back to the hash.
+ */
+export declare function refNameColor(name: string, position: number | undefined): string;
+export { category10, set1 };

package/esm/ui/colors.js

@@ -1,3 +1,4 @@
+import { relight } from '../util/color/index.js';
 const category10 = [
     '#1f77b4',
     '#ff7f0e',
@@ -64,4 +65,137 @@ const ggplot2Colors6 = [
 const ggplot2Colors5 = ['#F8766D', '#A3A500', '#00BF7D', '#00B0F6', '#E76BF3'];
 const ggplot2Colors4 = ['#F8766D', '#7CAE00', '#00BFC4', '#C77CFF'];
 const ggplot2Colors3 = ['#F8766D', '#00BA38', '#619CFF'];
-export { category10, dark2, ggplot2Colors3, ggplot2Colors4, ggplot2Colors5, ggplot2Colors6, set1, set2, tableau10, };
+// A neutral has no place in a categorical palette that paints FILLS. Grey reads
+// as "uncolored / no value" — it is what `randomColor` hands a value-less
+// feature, what a synteny ribbon defaults to, what alignments paint a read with
+// no tag — so a category landing on one says the opposite of what the palette
+// is for. `refNameColorHexes` below drops category10's grey for this reason and
+// has since it was written; this is the same rule applied to every scheme at
+// once.
+const NEUTRALS = new Set([
+    '#bab0ab',
+    '#999999',
+    '#666666',
+    '#b3b3b3',
+    '#7f7f7f',
+]);
+export const paletteColors = {
+    category10,
+    dark2,
+    ggplot2Colors3,
+    ggplot2Colors4,
+    ggplot2Colors5,
+    ggplot2Colors6,
+    set1,
+    set2,
+    tableau10,
+};
+/**
+ * The wide qualitative palette: every scheme above, in order, deduped and with
+ * the neutrals dropped. ~40 entries.
+ *
+ * One list, because "give each row a distinct color" is one question this repo
+ * answers in two places — the multi-row painter handing colors out by row
+ * index, and the arrangement dialog's palette-by-attribute — and two lists
+ * would mean a track's automatic colors and the colors it takes when a user
+ * palettes it by hand were different palettes for no reason a reader could see.
+ *
+ * `tableau10` leads because its hues are the most evenly separated, so a track
+ * with a handful of rows spends only that. The tail is what makes the 26
+ * 1000-Genomes population codes, or a repeat painting's classes, all get a
+ * curated color instead of falling out to `randomColor`.
+ *
+ * Past the end is the caller's problem, and the two callers answer differently
+ * on purpose: an attribute palette-by hashes the VALUE (stable across
+ * re-palettes), while a by-position painter has no value to hash and wraps.
+ */
+export const categoricalPalette = [
+    ...new Set([...tableau10, ...set1, ...dark2, ...set2, ...category10].filter(hex => !NEUTRALS.has(hex.toLowerCase()))),
+];
+// only category10 and set1 are imported by name; the rest are reached through
+// paletteColors above
+/**
+ * Deterministic non-negative 32-bit hash of a string.
+ */
+export function hashString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash |= 0;
+    }
+    return Math.abs(hash);
+}
+/**
+ * Stable category10 color for a sequence name, via `hashString`.
+ *
+ * Kept as a published export; in-tree, prefer {@link refNameColor}, which hands
+ * the palette out by position where the caller knows the assembly's chromosome
+ * order and only hashes where it does not.
+ */
+export function getQueryColor(queryName) {
+    return category10[hashString(queryName) % category10.length];
+}
+// The by-refName painting palette: category10 with its grey dropped, since a
+// grey chromosome reads as "uncolored/broken" (see NEUTRALS).
+//
+// category10 rather than the wide `categoricalPalette` — a karyotype wants nine
+// hues it can re-light into tones a reader can compare, not forty unrelated
+// ones, and `PALETTE_LAP_TONES` below is what that costs.
+const refNameColorHexes = category10.filter(hex => !NEUTRALS.has(hex));
+// Nine do not cover a karyotype, so each LAP around the list re-lights the same
+// hues: chromosome 10 is a deep version of chromosome 1's blue, chromosome 19 a
+// pale one. Three laps is 27 colors, past every karyotype these figures anchor
+// on (human 24, rice 12, bread wheat 21), and a fourth lap starts the tones
+// again rather than fading to nothing — a repeat 27 positions away is one no
+// reader is comparing.
+//
+// THE COLORS ARE THE PALETTE'S, not a ramp's. This spent a round as the next hue
+// on the golden angle at a fixed HSL 70%/50%, which is collision-free for any
+// karyotype and was rejected on sight by figure review ("the previous palette is
+// better"): an even hue circle at one saturation is a rainbow, and a five-genome
+// synteny figure drawn in one is a hundred thousand ribbons of pure red, green,
+// blue and magenta. category10's nine are uneven on purpose — that is what makes
+// them read as a set.
+//
+// It is not the weaker option for distinguishability either, which is what the
+// ramp was reached for. Closest pair in OKLab over 24 positions: 0.077 for these
+// laps, 0.019 for the golden angle at HSL 70%/50% — an even hue circle is even
+// in HSL's hue, and HSL's hue is not perceptually even.
+const PALETTE_LAP_TONES = [
+    // lap 0 is the palette color itself, untouched
+    undefined,
+    // deep before pale, because these are drawn at a low alpha over white (the
+    // OrthoFinder figures run at 0.06) and a pale color at 0.06 is a color a
+    // reader cannot see. Chroma held, and the gamut takes what it must down here.
+    { lightnessShift: -0.17, chromaScale: 1 },
+    // pale. Chroma comes down with lightness: held at full, the light lap's reds
+    // and pinks all pin against the top of the sRGB gamut and converge there.
+    { lightnessShift: 0.18, chromaScale: 0.8 },
+];
+/** The palette color for a chromosome at `position` in its assembly. */
+export function refNamePaletteColorAt(position) {
+    const hex = refNameColorHexes[position % refNameColorHexes.length];
+    const lap = PALETTE_LAP_TONES[Math.floor(position / refNameColorHexes.length) % PALETTE_LAP_TONES.length];
+    return lap ? relight(hex, lap.lightnessShift, lap.chromaScale) : hex;
+}
+/**
+ * The color a refName paints, BY POSITION IN THE ASSEMBLY where the caller
+ * knows its chromosome order.
+ *
+ * Handing the palette out rather than hashing into it is what stops a genome
+ * painting two of its own chromosomes the same color: nine slots means ten or
+ * more chromosomes re-use one, and by the birthday bound long before that. On
+ * hg38 the hash puts chr1, chr12, chr21 and chrY on one color.
+ *
+ * `position` is undefined for the case the order genuinely is not available —
+ * an assembly still loading, or a refName the assembly does not list (a
+ * scaffold under an alias). There a stable arbitrary color beats no color, so
+ * it falls back to the hash.
+ */
+export function refNameColor(name, position) {
+    return position === undefined
+        ? refNameColorHexes[hashString(name) % refNameColorHexes.length]
+        : refNamePaletteColorAt(position);
+}
+export { category10, set1 };

package/esm/ui/extensionSelectors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Which tracks a contribution is for. Every track-scoped extension point fires
+ * for every track, so a contribution with no selector applies to all of them.
+ * {@link matchesTrackSelector} is what applies one.
+ */
+export interface TrackSelector {
+    /** track type, e.g. `'VariantTrack'`, usually what "for my tracks" means */
+    trackType?: string | string[];
+    /** track id; a plain string also matches the user's copies of that track */
+    trackId?: string | RegExp | (string | RegExp)[];
+    /** widget model type, e.g. `'AlignmentsFeatureWidget'`, for the slot points */
+    widgetType?: string | string[];
+}
+/** the model fields a declarative selector can match on */
+export interface SelectableModel {
+    type?: string;
+    trackId?: string;
+    trackType?: string;
+}
+/**
+ * What a track-scoped extension point contribution is for: whether the widget
+ * model or track config in `subject` satisfies every field of `select`. Every
+ * field given must match, and an empty selector matches everything.
+ *
+ * Every one of those points fires for every track, so a contribution that does
+ * not call this applies to all of them. Hand-writing `config.trackId === 'x'`
+ * instead is what silently stops applying the first time a user copies the
+ * track: `copyTrackSnapshot` suffixes the id, and this knows that.
+ *
+ * Not to be confused with {@link matchTrackId}, which tests an id against
+ * patterns you supply and so leaves that normalization to you.
+ */
+export declare function matchesTrackSelector(select: TrackSelector | undefined, subject: {
+    /** a widget model, if the point's props carry one */
+    model?: SelectableModel;
+    /** a track config, if they carry that instead — `type` is the track type */
+    config?: Record<string, unknown>;
+}): boolean;

package/esm/ui/extensionSelectors.js

@@ -0,0 +1,49 @@
+import { matchTrackId } from '../util/matchTrackId.js';
+// "Copy track" appends `-${Date.now()}` to the trackId (copyTrackSnapshot), and
+// copying a copy appends again, so a bare id in a selector means "this track,
+// including the user's copies of it". Doing this in the framework is the point:
+// scoping by `trackId ===` is what people write by hand, and it silently stops
+// applying the moment a user copies the track.
+function matchesTrackId(trackId, pattern) {
+    return typeof pattern === 'string'
+        ? trackId === pattern ||
+            (trackId?.startsWith(`${pattern}-`) === true &&
+                trackId
+                    .slice(pattern.length + 1)
+                    .split('-')
+                    .every(part => /^\d+$/.test(part)))
+        : matchTrackId(trackId, [pattern]);
+}
+function matchesOneOf(value, expected) {
+    return typeof expected === 'string'
+        ? value === expected
+        : expected.includes(value ?? '');
+}
+/** Whether `model` satisfies every declarative field of `select`. */
+function selectorMatchesModel(select, model) {
+    const { widgetType, trackType, trackId } = select ?? {};
+    return ((widgetType === undefined || matchesOneOf(model.type, widgetType)) &&
+        (trackType === undefined || matchesOneOf(model.trackType, trackType)) &&
+        (trackId === undefined ||
+            (Array.isArray(trackId) ? trackId : [trackId]).some(pattern => matchesTrackId(model.trackId, pattern))));
+}
+/**
+ * What a track-scoped extension point contribution is for: whether the widget
+ * model or track config in `subject` satisfies every field of `select`. Every
+ * field given must match, and an empty selector matches everything.
+ *
+ * Every one of those points fires for every track, so a contribution that does
+ * not call this applies to all of them. Hand-writing `config.trackId === 'x'`
+ * instead is what silently stops applying the first time a user copies the
+ * track: `copyTrackSnapshot` suffixes the id, and this knows that.
+ *
+ * Not to be confused with {@link matchTrackId}, which tests an id against
+ * patterns you supply and so leaves that normalization to you.
+ */
+export function matchesTrackSelector(select, subject) {
+    const { model, config } = subject;
+    return selectorMatchesModel(select, model ?? {
+        trackId: config?.trackId,
+        trackType: config?.type,
+    });
+}

package/esm/ui/filterMenuItems.d.ts

@@ -0,0 +1,112 @@
+import type { MenuItem } from './MenuTypes.ts';
+/**
+ * One reversible piece of display state — a filter, a hidden set, a collected
+ * "show only these", a highlight set — declared once so that the three things a
+ * display currently derives separately all come from the same place: how many
+ * of them are in effect, the row offered to undo this one, and the group-level
+ * "clear everything".
+ *
+ * It exists because those three drifted apart, repeatedly and silently, and the
+ * failures are invisible rather than loud:
+ *
+ * - a set with no undo row at all (canvas `pinnedFeatureIds`: persistent,
+ *   layout-affecting, and reachable only from the pinned feature's own
+ *   right-click menu, so a pin left on another chromosome could not be reached);
+ * - an undo derived from the state's ABSENCE, so it vanished with the thing it
+ *   undid (the canvas colour key's "×" was a one-way door for the session);
+ * - a count derived from a different predicate than the state's actual effect
+ *   ("Filter by... (1)" for opening the filter dialog and pressing Submit).
+ *
+ * The pairing rule that used to live in a comment — *every filter counted must
+ * be reset by the clear, or the menu offers a recovery that doesn't recover* —
+ * is structural once both sides read this list.
+ */
+export interface Reversible {
+    /** How many independent things this is holding. 0 = not in effect. */
+    count: number;
+    /**
+     * Row text for undoing just this one, given its count. Omit for state whose
+     * only sensible undo is the group's "clear all" — a jexl filter list has no
+     * per-item recovery to name.
+     */
+    label?: (count: number) => string;
+    icon?: React.ElementType;
+    /** Reverse it. Must be a no-op when `count` is 0. */
+    clear: () => void;
+}
+/**
+ * A display's reversibles, keyed by name — `{ hiddenFeatures: {...}, solo: {...} }`.
+ * A record rather than an array so a consumer wanting one specific entry (the
+ * feature context menu offers "Show N hidden features" without the rest of the
+ * family) reads `.hiddenFeatures` and is type-checked, instead of searching a
+ * list for a string id. Row order is the record's insertion order.
+ */
+export type Reversibles = Record<string, Reversible>;
+/** Total in effect — what a "(n)" in a group label counts. */
+export declare function activeCount(items: Reversibles): number;
+/**
+ * Reverse every one. Inactive entries are cleared too (their `clear` is a
+ * no-op), so this stays a plain fold rather than a filtered one — a caller
+ * cannot half-clear by getting the gate wrong.
+ */
+export declare function clearAll(items: Reversibles): void;
+/**
+ * The undo rows: one per entry that is in effect AND names itself. Spread,
+ * don't insert — an entry holding nothing contributes nothing.
+ */
+export declare function undoItems(items: Reversibles, priority?: number): MenuItem[];
+export interface FilterMenuOpts {
+    /**
+     * The display's narrowings, declared once (see {@link Reversible}). Supplying
+     * this derives `activeCount`, `recoveryItems` and `onClear` together, so the
+     * count in the label, the rows inside the submenu and what "Clear all filters"
+     * actually clears cannot disagree. Prefer it to spelling the three out.
+     */
+    narrowings?: Reversibles;
+    /**
+     * How many independent filters are narrowing the view right now, so the label
+     * can say that something is hiding data. Count a filter when its value is not
+     * its **no-op** value, which is not always its config default: the LD
+     * display's `minorAlleleFrequencyFilter` ships at 0.1 and is genuinely
+     * dropping variants, while the alignments flag masks default non-zero and are
+     * the no-filtering state, so they count only when edited away from it.
+     *
+     * This is usually the only affordance telling the user a filter is silently
+     * hiding rows — nothing else in the track chrome says so.
+     *
+     * Ignored when `narrowings` is given.
+     */
+    activeCount?: number;
+    /** Opens the display's filter dialog, where it has a single one. */
+    onEdit?: () => void;
+    /** Controls that belong inside the submenu (inline sliders, further dialogs). */
+    subItems?: MenuItem[];
+    /**
+     * Recovery rows offered alongside "Clear all filters" once something is
+     * filtering — the canvas display's "Show N hidden features", for one.
+     */
+    recoveryItems?: MenuItem[];
+    /** Turn every filter off. Offered only while `activeCount` is non-zero. */
+    onClear?: () => void;
+    /** Rides the top-level row; see the canvas display's RECOVERY_PRIORITY. */
+    priority?: number;
+    /** Label for the dialog opener inside the submenu. */
+    editLabel?: string;
+}
+/**
+ * The "Filter by..." family, in the one shape every display uses.
+ *
+ * On a track with nothing to recover this is the single dialog opener, because
+ * a submenu wrapping one row is pure indirection. Once filters are on — or a
+ * display contributes its own inline controls — the recovery rows join it and
+ * the group earns its submenu, with the dialog opener as its first row.
+ *
+ * Spread, don't insert: a display with neither a dialog nor sub-items (a
+ * pre-computed LD file has nothing to filter) contributes no row at all.
+ *
+ * Written once because the four copies had drifted into four designs, and only
+ * the alignments one put the active count in the label — so a filtered LD or
+ * multi-sample variant track said nothing, anywhere, about the rows it was
+ * dropping.
+ */
+export declare function filterMenuItems({ narrowings, activeCount: explicitCount, onEdit, subItems, recoveryItems: explicitRecovery, onClear: explicitClear, priority, editLabel, }: FilterMenuOpts): MenuItem[];