@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/assemblyConfigUtils.js

@@ -0,0 +1,498 @@
+import { getFileName } from './getFileName.js';
+import { isLocalPathLocation, isUriLocation } from './types/data.js';
+// Shared assembly "add sequence" form logic used by both the jbrowse-desktop
+// Open genome(s) dialog and the in-app data-management Assembly manager. Pure
+// (no React, no MST, no product wiring) so it can live in core and be reused by
+// both surfaces. The one product-specific step — turning a plain FASTA into a
+// usable adapter — is injected into buildAssemblyConf (desktop runs samtools
+// faidx to produce an IndexedFastaAdapter; web keeps an UnindexedFastaAdapter).
+export const adapterTypes = [
+    'IndexedFastaAdapter',
+    'BgzipFastaAdapter',
+    'FastaAdapter',
+    'TwoBitAdapter',
+    'ChromSizesAdapter',
+];
+export const adapterLabels = {
+    IndexedFastaAdapter: 'FASTA with index (.fa + .fai)',
+    BgzipFastaAdapter: 'Compressed FASTA (.fa.gz + .fai + .gzi)',
+    FastaAdapter: 'FASTA (automatically indexed)',
+    TwoBitAdapter: '2bit file (.2bit)',
+    ChromSizesAdapter: 'Chromosome sizes, no sequence (.chrom.sizes)',
+};
+// The formats that bring bases with them. ChromSizesAdapter is the one that
+// does not: it names the assembly's sequences and their lengths and stops
+// there, which is the whole point of it (six wheat genomes are tens of
+// gigabytes as sequence and a few kilobytes as names and lengths) and also
+// everything a caller has to warn about. `jbrowse add-assembly` has taken
+// `--type chromSizes` since long before this pane offered it.
+export function adapterHasSequence(adapterSelection) {
+    return adapterSelection !== 'ChromSizesAdapter';
+}
+export const sidecarRoles = ['fai', 'gzi'];
+// What each index sidecar is called, where it lives on the form, and the
+// extension it takes next to its sequence file.
+export const sidecars = {
+    fai: {
+        field: 'faiLocation',
+        ext: '.fai',
+        label: 'FASTA index (.fai) file',
+    },
+    gzi: {
+        field: 'gziLocation',
+        ext: '.gzi',
+        label: 'FASTA gzip index (.gzi) file',
+    },
+};
+// The sidecars each format cannot load without. One table because the same
+// condition was written out at four sites and they drifted: the staging button
+// gated on a copy that let a .fa.gz through with neither index, straight into
+// getAdapterConfig's "FASTA, FAI, and GZI locations are all required".
+const requiredSidecars = {
+    IndexedFastaAdapter: ['fai'],
+    BgzipFastaAdapter: ['fai', 'gzi'],
+    FastaAdapter: [],
+    TwoBitAdapter: [],
+    ChromSizesAdapter: [],
+};
+// The file each format is opened by. A table rather than an `=== 'TwoBit'` test
+// per site, because chrom.sizes is the primary for one format and a 2bit's
+// optional sidecar for another, and the two answers were about to be spelled
+// out at three call sites.
+const primaryFields = {
+    IndexedFastaAdapter: 'fastaLocation',
+    BgzipFastaAdapter: 'fastaLocation',
+    FastaAdapter: 'fastaLocation',
+    TwoBitAdapter: 'twoBitLocation',
+    ChromSizesAdapter: 'chromSizesLocation',
+};
+// Curried field setter for the add-assembly form:
+// makeSetField(setForm)('faiLocation') returns a value setter that merges just
+// that field. Shared by AdvancedOptions and SequenceAdapterInputs so the
+// immutable-update logic lives in one place.
+export function makeSetField(setForm) {
+    return (key) => (value) => {
+        setForm(f => ({ ...f, [key]: value }));
+    };
+}
+const blank = { uri: '', locationType: 'UriLocation' };
+export function initialFormState() {
+    return {
+        adapterSelection: adapterTypes[0],
+        assemblyName: '',
+        assemblyDisplayName: '',
+        fastaLocation: blank,
+        faiLocation: blank,
+        gziLocation: blank,
+        twoBitLocation: blank,
+        chromSizesLocation: blank,
+        refNameAliasesLocation: blank,
+        cytobandsLocation: blank,
+    };
+}
+export function applyPrimaryFile(state, location) {
+    const filename = getFileName(location);
+    const detected = filename ? detectAdapterType(filename) : undefined;
+    const assemblyName = filename && !state.assemblyName
+        ? getAssemblyNameFromFilename(filename)
+        : state.assemblyName;
+    if (detected === 'TwoBitAdapter' || detected === 'ChromSizesAdapter') {
+        return {
+            ...state,
+            [primaryFields[detected]]: location,
+            adapterSelection: detected,
+            assemblyName,
+        };
+    }
+    const adapterSelection = detected ?? state.adapterSelection;
+    return {
+        ...state,
+        fastaLocation: location,
+        adapterSelection,
+        assemblyName,
+        ...guessSidecarLocations(state, location, adapterSelection),
+    };
+}
+// Prefill conventional .fai/.gzi sidecars sitting next to the chosen FASTA,
+// leaving any field the user already set untouched. Spreading the source
+// location carries over its baseUri/auth so the sidecars use the same access.
+function guessSidecarLocations(state, location, adapterSelection) {
+    const guesses = {};
+    for (const role of requiredSidecars[adapterSelection]) {
+        const { field, ext } = sidecars[role];
+        const guess = isBlank(state[field]) ? sidecar(location, ext) : undefined;
+        if (guess) {
+            guesses[field] = guess;
+        }
+    }
+    return guesses;
+}
+function sidecar(location, ext) {
+    if (isUriLocation(location)) {
+        return { ...location, uri: `${location.uri}${ext}` };
+    }
+    if (isLocalPathLocation(location)) {
+        return { ...location, localPath: `${location.localPath}${ext}` };
+    }
+    return undefined;
+}
+export function applyTwoBitFile(state, location) {
+    const filename = getFileName(location);
+    const assemblyName = filename && !state.assemblyName
+        ? getAssemblyNameFromFilename(filename)
+        : state.assemblyName;
+    return { ...state, twoBitLocation: location, assemblyName };
+}
+// Everything about the genome just staged, gone, so the next one starts clean.
+// The chosen format survives on purpose: in the manual form it is what the user
+// picked, and the guided path overwrites it from the next file set anyway.
+export function clearFormFields(state) {
+    return { ...initialFormState(), adapterSelection: state.adapterSelection };
+}
+// Clear only the sequence-file fields (and their required index sidecars),
+// keeping assembly-level metadata the user already entered — name, display name,
+// refName aliases, cytobands. Used by the recognition card's "change" link so
+// swapping a mis-picked sequence file doesn't discard everything else.
+export function clearSequenceFiles(state) {
+    return {
+        ...state,
+        fastaLocation: blank,
+        faiLocation: blank,
+        gziLocation: blank,
+        twoBitLocation: blank,
+        chromSizesLocation: blank,
+    };
+}
+export function getBaseAssemblyConfig(state) {
+    return {
+        name: state.assemblyName,
+        ...(state.assemblyDisplayName
+            ? { displayName: state.assemblyDisplayName }
+            : {}),
+        ...(!isBlank(state.refNameAliasesLocation)
+            ? {
+                refNameAliases: {
+                    adapter: {
+                        type: 'RefNameAliasAdapter',
+                        location: state.refNameAliasesLocation,
+                    },
+                },
+            }
+            : {}),
+        ...(!isBlank(state.cytobandsLocation)
+            ? {
+                cytobands: {
+                    adapter: {
+                        type: 'CytobandAdapter',
+                        cytobandLocation: state.cytobandsLocation,
+                    },
+                },
+            }
+            : {}),
+    };
+}
+export function isBlank(location) {
+    return 'uri' in location && location.uri === '';
+}
+// The form can be opened only once the chosen format's primary file is there.
+// Secondary files (.fai/.gzi) are validated later in getAdapterConfig.
+export function formHasSequence(form) {
+    return !isBlank(form[primaryFields[form.adapterSelection]]);
+}
+// The name the assembly is saved under. Trimmed because surrounding whitespace
+// is never intentional and would otherwise create near-duplicate assemblies
+// ("hg38" vs "hg38 ") that a caller's duplicate check can't catch.
+export function getAssemblyName(form) {
+    return form.assemblyName.trim();
+}
+// The index files the chosen format requires that the form doesn't have yet.
+// getAdapterConfig throws on the same condition; asking first is what lets a
+// caller disable its submit button instead of letting the user click it and
+// read a stack trace back, and lets the pane offer an input for each one.
+export function getMissingSidecars(form) {
+    return requiredSidecars[form.adapterSelection]
+        .map(role => sidecars[role])
+        .filter(({ field }) => isBlank(form[field]));
+}
+// Whether the form can be submitted/staged: a primary sequence file, everything
+// that file's format requires, and a (non-whitespace) name. Shared so every
+// add-assembly surface gates its submit button the same way.
+export function isFormReady(form) {
+    return (formHasSequence(form) &&
+        !!getAssemblyName(form) &&
+        !getMissingSidecars(form).length);
+}
+// Whether the user has put anything in the form. A caller that submits a
+// separate list (desktop stages several genomes) uses this to refuse rather
+// than silently drop a genome the user was halfway through entering.
+export function isFormDirty(form) {
+    return formHasSequence(form) || !!getAssemblyName(form);
+}
+// The non-primary files the built config will actually reference, and the ones
+// it won't. chrom.sizes reaches a TwoBitAdapter and nothing else, so listing it
+// under a FASTA promises a file getAdapterConfig drops on the floor.
+export function partitionExtraLocations(form) {
+    const { adapterSelection } = form;
+    const required = requiredSidecars[adapterSelection];
+    // it is the primary file for ChromSizesAdapter and listed by the row above
+    // the extras, so it belongs in neither list there
+    const chromSizesReaches = adapterSelection === 'TwoBitAdapter' ||
+        adapterSelection === 'ChromSizesAdapter';
+    const sidecarLocation = (role) => form[sidecars[role].field];
+    const used = [
+        ...required.map(sidecarLocation),
+        ...(adapterSelection === 'TwoBitAdapter' ? [form.chromSizesLocation] : []),
+        form.refNameAliasesLocation,
+        form.cytobandsLocation,
+    ].filter(loc => !isBlank(loc));
+    const unused = [
+        ...sidecarRoles
+            .filter(role => !required.includes(role))
+            .map(sidecarLocation),
+        ...(chromSizesReaches ? [] : [form.chromSizesLocation]),
+    ].filter(loc => !isBlank(loc));
+    return { used, unused };
+}
+// The FASTA extensions the sequence plugin's adapter guessers accept, so the
+// add-genome pane places exactly the files that load everywhere else. Its own
+// table used to be `(fa|fasta|fna).gz`, case-sensitive, which silently refused
+// .fas, .mfa, .FA and .fa.bgz.
+const FASTA_EXT = /\.(fa|fasta|fas|fna|mfa)$/i;
+const FASTA_GZ_EXT = /\.(fa|fasta|fas|fna|mfa)\.b?gz$/i;
+const TWOBIT_EXT = /\.2bit$/i;
+// the same pattern `jbrowse add-assembly` infers `--type chromSizes` from, so a
+// file that works there is recognized here
+const CHROM_SIZES_EXT = /\.chrom\.sizes$/i;
+// Every pattern here anchors to the end of the name, which is why getFileName
+// drops a URI's query string — a presigned link's few hundred characters of
+// signature would otherwise be what these match against.
+export function getAssemblyNameFromFilename(filename) {
+    return filename
+        .replace(FASTA_GZ_EXT, '')
+        .replace(FASTA_EXT, '')
+        .replace(TWOBIT_EXT, '')
+        .replace(CHROM_SIZES_EXT, '');
+}
+export function detectAdapterType(filename) {
+    return FASTA_GZ_EXT.test(filename)
+        ? 'BgzipFastaAdapter'
+        : TWOBIT_EXT.test(filename)
+            ? 'TwoBitAdapter'
+            : CHROM_SIZES_EXT.test(filename)
+                ? 'ChromSizesAdapter'
+                : undefined;
+}
+// Classify a single filename into the assembly slot it belongs to, by
+// extension. Returns undefined for files we can't place. Order matters: index
+// sidecars (.fai/.gzi) are checked before the fasta patterns they share a stem
+// with, and the fasta patterns before the looser cytoband/alias name matches.
+export function classifyFilename(filename) {
+    return /\.fai$/i.test(filename)
+        ? 'fai'
+        : /\.gzi$/i.test(filename)
+            ? 'gzi'
+            : TWOBIT_EXT.test(filename)
+                ? 'twoBit'
+                : FASTA_GZ_EXT.test(filename)
+                    ? 'fastaGz'
+                    : FASTA_EXT.test(filename)
+                        ? 'fasta'
+                        : /\.chrom\.sizes$/i.test(filename)
+                            ? 'chromSizes'
+                            : /cytoband/i.test(filename)
+                                ? 'cytobands'
+                                : /alias/i.test(filename)
+                                    ? 'refNameAliases'
+                                    : undefined;
+}
+// Sort a dropped/pasted set of files into the assembly form fields, picking the
+// adapter and assembly name from whichever file is the primary sequence.
+//
+// The primary is chosen once, up front, and then answers for the adapter, the
+// sequence field and the name together. Letting each branch overwrite as it went
+// ran two independent last-wins rules that could disagree: a .2bit ahead of a .fa
+// took the adapter while the .fa took the name, so the form opened one genome's
+// sequence under the other genome's name, and the "more than one genome" notice
+// named the file it was not reading.
+export function classifyAssemblyFiles(locations) {
+    const result = {};
+    const classified = classifyLocations(locations);
+    for (const { location, role } of classified) {
+        const field = role && extraFields[role];
+        if (field) {
+            result[field] = location;
+        }
+    }
+    const primary = classified.filter(f => isSequenceRole(f.role)).at(-1);
+    // A chrom.sizes leads only when nothing that carries bases is in the set: it
+    // is the 2bit's optional sequence-name sidecar in every other drop, and
+    // promoting it would silently downgrade `hg38.2bit + hg38.chrom.sizes` to an
+    // assembly with no sequence.
+    if (!primary && !isBlank(result.chromSizesLocation ?? blank)) {
+        return {
+            ...result,
+            adapterSelection: 'ChromSizesAdapter',
+            assemblyName: getAssemblyNameFromFilename(getFileName(result.chromSizesLocation)),
+        };
+    }
+    if (primary) {
+        result.assemblyName = getAssemblyNameFromFilename(getFileName(primary.location));
+        if (primary.role === 'twoBit') {
+            result.twoBitLocation = primary.location;
+            result.adapterSelection = 'TwoBitAdapter';
+        }
+        else {
+            result.fastaLocation = primary.location;
+            result.adapterSelection =
+                primary.role === 'fastaGz'
+                    ? 'BgzipFastaAdapter'
+                    : // a plain FASTA with no .fai in the set indexes itself on submit
+                        result.faiLocation
+                            ? 'IndexedFastaAdapter'
+                            : 'FastaAdapter';
+        }
+    }
+    return result;
+}
+// The roles that describe the sequence itself. Exactly one of these is the
+// genome being added, so a set holding two holds two genomes and the caller
+// warns about it.
+const sequenceRoles = new Set([
+    'fasta',
+    'fastaGz',
+    'twoBit',
+]);
+export function isSequenceRole(role) {
+    return role !== undefined && sequenceRoles.has(role);
+}
+// Where each non-sequence role lands on the form. The sequence roles map to
+// nothing on purpose: which field they fill depends on which one is the primary,
+// so classifyAssemblyFiles decides that in one place rather than per file.
+const extraFields = {
+    fai: 'faiLocation',
+    gzi: 'gziLocation',
+    chromSizes: 'chromSizesLocation',
+    cytobands: 'cytobandsLocation',
+    refNameAliases: 'refNameAliasesLocation',
+    fasta: undefined,
+    fastaGz: undefined,
+    twoBit: undefined,
+};
+// Every location paired with the slot it belongs in, `undefined` for the ones
+// that could not be placed. Callers needing more than one answer about the same
+// set — what was placed, what wasn't, which files are sequences — get all of
+// them out of this one pass.
+export function classifyLocations(locations) {
+    return locations.map(location => ({
+        location,
+        role: classifyFilename(getFileName(location)),
+    }));
+}
+/**
+ * Rebuild the file-location fields (plus adapter/name) of `state` from a freshly
+ * classified set of dropped/pasted files.
+ *
+ * The file set is authoritative: a field it says nothing about resets, so
+ * deleting a URL from the box clears the slot it filled. `edited` is the way out
+ * — the fields the user set by hand, which the classifier never gets to answer
+ * for. Without it, typing a .fai into the "this format needs its index" input
+ * and then adding one more URL wiped the .fai and the pane re-asked for it.
+ *
+ * refName aliases and cytobands merge instead of resetting even when untouched:
+ * they are the two slots "More options" also fills, and no file set that omits
+ * them is making a claim about them.
+ */
+export function applyClassifiedFiles(state, locations, edited) {
+    const classified = classifyAssemblyFiles(locations);
+    const pick = (key, reset) => edited.has(key) ? state[key] : (classified[key] ?? reset);
+    return {
+        ...state,
+        fastaLocation: pick('fastaLocation', blank),
+        faiLocation: pick('faiLocation', blank),
+        gziLocation: pick('gziLocation', blank),
+        twoBitLocation: pick('twoBitLocation', blank),
+        chromSizesLocation: pick('chromSizesLocation', blank),
+        refNameAliasesLocation: pick('refNameAliasesLocation', state.refNameAliasesLocation),
+        cytobandsLocation: pick('cytobandsLocation', state.cytobandsLocation),
+        adapterSelection: pick('adapterSelection', state.adapterSelection),
+        assemblyName: pick('assemblyName', ''),
+    };
+}
+// Build a full assembly config from the form. A plain FASTA has no index, so
+// the caller supplies a resolveFastaAdapter callback (desktop runs an
+// out-of-process samtools faidx to make an IndexedFastaAdapter; web keeps an
+// UnindexedFastaAdapter) used only for the needsFastaIndex case. The name is
+// trimmed and reused for a unique-per-open sequence trackId.
+export async function buildAssemblyConf(form, resolveFastaAdapter) {
+    const name = getAssemblyName(form);
+    const result = getAdapterConfig(form);
+    const adapter = result.kind === 'needsFastaIndex'
+        ? await resolveFastaAdapter(result.fastaLocation)
+        : result.adapter;
+    return {
+        ...getBaseAssemblyConfig({ ...form, assemblyName: name }),
+        sequence: {
+            type: 'ReferenceSequenceTrack',
+            trackId: `${name}-${Date.now()}`,
+            adapter,
+        },
+    };
+}
+export function urlTextToLocations(text) {
+    return text
+        .split('\n')
+        .map(line => line.trim())
+        .filter(Boolean)
+        .map(uri => ({ uri, locationType: 'UriLocation' }));
+}
+export function getAdapterConfig({ adapterSelection, fastaLocation, faiLocation, gziLocation, twoBitLocation, chromSizesLocation, }) {
+    if (adapterSelection === 'FastaAdapter') {
+        if (isBlank(fastaLocation)) {
+            throw new Error('FASTA location is required');
+        }
+        return { kind: 'needsFastaIndex', fastaLocation };
+    }
+    if (adapterSelection === 'IndexedFastaAdapter') {
+        if (isBlank(fastaLocation) || isBlank(faiLocation)) {
+            throw new Error('Both FASTA and FAI locations are required');
+        }
+        return {
+            kind: 'ready',
+            adapter: { type: 'IndexedFastaAdapter', fastaLocation, faiLocation },
+        };
+    }
+    if (adapterSelection === 'BgzipFastaAdapter') {
+        if (isBlank(fastaLocation) ||
+            isBlank(faiLocation) ||
+            isBlank(gziLocation)) {
+            throw new Error('FASTA, FAI, and GZI locations are all required');
+        }
+        return {
+            kind: 'ready',
+            adapter: {
+                type: 'BgzipFastaAdapter',
+                fastaLocation,
+                faiLocation,
+                gziLocation,
+            },
+        };
+    }
+    if (adapterSelection === 'ChromSizesAdapter') {
+        if (isBlank(chromSizesLocation)) {
+            throw new Error('Chromosome sizes location is required');
+        }
+        return {
+            kind: 'ready',
+            adapter: { type: 'ChromSizesAdapter', chromSizesLocation },
+        };
+    }
+    if (isBlank(twoBitLocation)) {
+        throw new Error('2bit location is required');
+    }
+    return {
+        kind: 'ready',
+        adapter: isBlank(chromSizesLocation)
+            ? { type: 'TwoBitAdapter', twoBitLocation }
+            : { type: 'TwoBitAdapter', twoBitLocation, chromSizesLocation },
+    };
+}

package/esm/util/bandHeight.d.ts

@@ -0,0 +1,53 @@
+export declare const MIN_BAND_HEIGHT = 20;
+/** The legal range for one band. Both ends are optional and both are px. */
+export interface BandBounds {
+    /** Defaults to {@link MIN_BAND_HEIGHT}. */
+    min?: number;
+    /** Defaults to unbounded. A band above a plot should always state one. */
+    max?: number;
+}
+/**
+ * #api core/util
+ * Bound a band height to its legal range — a config value, a menu choice, or a
+ * slider position, i.e. anywhere the number is being *stated* rather than
+ * dragged.
+ *
+ * The **floor** keeps the band operable at its smallest: for a drag-resized
+ * band that means keeping the handle grabbable, for a menu-sized one it is the
+ * height below which its content stops reading. The **ceiling** stops a band
+ * from swallowing the plot it sits over — every display floors its plot area at
+ * 0, so an unbounded band takes the rows to zero height rather than to a
+ * scrollbar, and takes the band's own handle off-screen with them.
+ *
+ * The bounds differ per band and the rule does not, which is why this takes them
+ * rather than each band re-deriving the reasoning — that is how the two
+ * `clampBandHeight`s in this repo drifted apart, each ending up with one half of
+ * this rule and a doc comment claiming to be the whole of it.
+ */
+export declare function boundBandHeight(n: number, { min, max }?: BandBounds): number;
+/**
+ * #api core/util
+ * Clamp one *resize* of a drag-resizable band: {@link boundBandHeight}, plus the
+ * one rule a resize needs that a stated height does not.
+ *
+ * The floor becomes `min(bounds.min, current)`, never the bare bound: a band
+ * whose config declares it smaller than the floor must stay where it is. Taking
+ * the bare floor instead made the *first* drag on such a band jump it up to the
+ * floor before honoring the delta. A band at or above the floor is unaffected,
+ * one below it can still be dragged but never smaller than it already is, and
+ * one dragged back past the floor regains it.
+ *
+ * The ceiling is not relaxed the same way — a band already over its ceiling is
+ * the state the user is trying to escape, so a resize brings it back inside.
+ *
+ * `ResizeHandle` emits one delta per animation frame, so callers driving a drag
+ * pass `current + distance` as the target and read `current` inside the action —
+ * a component computing the target from a rendered height drops every tick that
+ * lands before React re-renders.
+ *
+ * @param current - the band's height right now, in px
+ * @param target - the height this resize is asking for, in px
+ * @param bounds - the band's legal range; `max` should be derived from the
+ *   display height so the plot below cannot be squashed to nothing
+ */
+export declare function clampBandHeight(current: number, target: number, bounds?: BandBounds): number;

package/esm/util/bandHeight.js

@@ -0,0 +1,56 @@
+// Default floor for a user-resizable band (an alignments coverage / arc /
+// sashimi band, a MAF coverage / conservation band), in px. It exists so the
+// drag handle stays grabbable, which is a constraint on dragging, not on what
+// config may declare. Bands with their own vocabulary of "too small" pass their
+// own (the variant lane's 8 is where a record stops reading as a mark).
+export const MIN_BAND_HEIGHT = 20;
+/**
+ * #api core/util
+ * Bound a band height to its legal range — a config value, a menu choice, or a
+ * slider position, i.e. anywhere the number is being *stated* rather than
+ * dragged.
+ *
+ * The **floor** keeps the band operable at its smallest: for a drag-resized
+ * band that means keeping the handle grabbable, for a menu-sized one it is the
+ * height below which its content stops reading. The **ceiling** stops a band
+ * from swallowing the plot it sits over — every display floors its plot area at
+ * 0, so an unbounded band takes the rows to zero height rather than to a
+ * scrollbar, and takes the band's own handle off-screen with them.
+ *
+ * The bounds differ per band and the rule does not, which is why this takes them
+ * rather than each band re-deriving the reasoning — that is how the two
+ * `clampBandHeight`s in this repo drifted apart, each ending up with one half of
+ * this rule and a doc comment claiming to be the whole of it.
+ */
+export function boundBandHeight(n, { min = MIN_BAND_HEIGHT, max = Number.POSITIVE_INFINITY } = {}) {
+    return Math.min(max, Math.max(min, Math.round(n)));
+}
+/**
+ * #api core/util
+ * Clamp one *resize* of a drag-resizable band: {@link boundBandHeight}, plus the
+ * one rule a resize needs that a stated height does not.
+ *
+ * The floor becomes `min(bounds.min, current)`, never the bare bound: a band
+ * whose config declares it smaller than the floor must stay where it is. Taking
+ * the bare floor instead made the *first* drag on such a band jump it up to the
+ * floor before honoring the delta. A band at or above the floor is unaffected,
+ * one below it can still be dragged but never smaller than it already is, and
+ * one dragged back past the floor regains it.
+ *
+ * The ceiling is not relaxed the same way — a band already over its ceiling is
+ * the state the user is trying to escape, so a resize brings it back inside.
+ *
+ * `ResizeHandle` emits one delta per animation frame, so callers driving a drag
+ * pass `current + distance` as the target and read `current` inside the action —
+ * a component computing the target from a rendered height drops every tick that
+ * lands before React re-renders.
+ *
+ * @param current - the band's height right now, in px
+ * @param target - the height this resize is asking for, in px
+ * @param bounds - the band's legal range; `max` should be derived from the
+ *   display height so the plot below cannot be squashed to nothing
+ */
+export function clampBandHeight(current, target, bounds = {}) {
+    const { min = MIN_BAND_HEIGHT } = bounds;
+    return boundBandHeight(target, { ...bounds, min: Math.min(min, current) });
+}

package/esm/util/bandLayout.d.ts

@@ -0,0 +1,51 @@
+import type { BandBounds } from './bandHeight.ts';
+/**
+ * #api core/util
+ * One band of a display's vertical stack — a coverage histogram, an arc strip,
+ * a conservation row, a variant lane. The contract is the pair: `active` is
+ * whether the band exists right now (the display pre-ANDs its settings half,
+ * `showX`, with its data half, "some lane has ink"), and `height` is the stated
+ * height when it does. Consumers read pixels through {@link reservedPx} or
+ * {@link stackBands}, never by re-combining the pair — the re-combination is
+ * where the reserver and the painter historically drifted.
+ */
+export interface Band {
+    active: boolean;
+    /** The stated height in px, meaningful only while `active`. */
+    height: number;
+    /**
+     * Present ⇒ `height` is bound at read time ({@link boundBandHeight}), for a
+     * band whose stored value may be stale or hand-edited. Absent ⇒ the stated
+     * height is trusted as-is; the setters are the only gate.
+     */
+    bounds?: BandBounds;
+}
+/**
+ * #api core/util
+ * The pixels a band takes from the plot below it: 0 when off, the (optionally
+ * bound) stated height when on. This is the single spelling of "off spends
+ * 0 px".
+ */
+export declare function reservedPx(band: Band): number;
+/** What {@link stackBands} derives: one top per band, and where the stack ends. */
+export interface BandStack<K extends string> {
+    /** Content-space y where each band begins, in stack order. */
+    top: Record<K, number>;
+    /** Each band's {@link reservedPx}. */
+    reserved: Record<K, number>;
+    /** Where the content below the stack begins — the sum of every reserved px. */
+    bottom: number;
+}
+/**
+ * #api core/util
+ * Fold an ordered set of bands into tops and a bottom. The order is the
+ * argument, so a display states its band order exactly once; reserve, paint
+ * and pick all read the same fold, which is what keeps "the reserver and the
+ * painter read one function" true by construction rather than by prose.
+ *
+ * Only the fold is shared. What varies per display stays there: per-lane
+ * iteration runs this once per lane, sticky-vs-scrolling is a property of how
+ * the result is projected to the screen, and a band drawn outside its
+ * reservation (an overlay) carries its own draw rect beside the stack.
+ */
+export declare function stackBands<K extends string>(order: readonly K[], bands: Record<K, Band>): BandStack<K>;