core/util

Auto-generated from exported functions tagged #api in the source. See imports and re-exports for how to import these from a plugin.

Band#

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 reservedPx or stackBands, never by re-combining the pair — the re-combination is where the reserver and the painter historically drifted.

Source code

boundBandHeight#

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 clampBandHeights 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.

// type signature
(n: number, { min, max }?: BandBounds) => number

Source code

canonicalizeViewRefName#

Resolve user-authored refName text against the assembly of the view containing node, resolving aliases and casing together. Falls back to the input when the assembly is absent or its aliases have not loaded.

Uses the view's assembly, not the track's, because displayed regions, loaded regions and blocks all carry the refNames the view laid out.

Call it wherever a refName a person wrote is about to be compared against regions, features or blocks, which carry the assembly's canonical name. A refName a display copied off a region is already canonical. One from a session spec, a config slot or a URL is whatever the author typed.

Without it, matching depends on the assembly: chr12 matches on an assembly canonicalized chr12 and matches nothing on one canonicalized 12. The same spec key works on one config and does nothing on the next, with no error.

Resolves through getCanonicalRefName2, which falls back to the input instead of throwing when a spec is read before the alias file has loaded. The getters that read user specs run from the first render.

Takes a refName, not a spec that might hold one. The resolver calls refName.toLowerCase(), so any other value throws once the aliases have loaded, and a caller reading an untyped frozen slot must first check that the value is a refName.

// type signature
(node: IAnyStateTreeNode, refName: string) => string

Source code

clampBandHeight#

Clamp one resize of a drag-resizable band: 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.

// type signature
(current: number, target: number, bounds?: BandBounds) => number

Source code

getAssemblyHost#

The host's assembly manager, for a module that resolves names and nothing else.

Unlike the accessors in sessionServices.ts this one buys the caller no smaller type graph — an AssemblyManager is an MST model a PluginManager built, so naming it costs what naming a session costs. It is here to say which service is wanted, and because that cost is the finding: the assembly manager is the one thing on AbstractSessionModel a third-party host cannot simply implement.

// type signature
(node: IAnyStateTreeNode) => AssemblyHost

Source code

getContainingDisplay#

Returns the display model that contains the given node. Throws if the node has no containing display.

// type signature
(node: IAnyStateTreeNode) => AbstractDisplayModel

Source code

getContainingTrack#

Returns the track model that contains the given node. Throws if the node has no containing track.

// type signature
(node: IAnyStateTreeNode) => AbstractTrackModel

Source code

getContainingView#

Returns the view model that contains the given node. Throws if the node has no containing view.

// type signature
(node: IAnyStateTreeNode) => AbstractViewModel

Source code

getDialogHost#

Where a display puts a dialog it cannot mount itself.

// type signature
(node: IAnyStateTreeNode) => DialogHost

Source code

getEnv#

Returns the MST environment for a node, which carries the pluginManager.

// type signature
(obj: IAnyStateTreeNode) => { pluginManager: PluginManager; }

Source code

getNotificationSink#

Where a display puts a message it cannot draw itself.

// type signature
(node: IAnyStateTreeNode) => NotificationSink

Source code

getPaletteHost#

The colors to draw with, and the args that rebuild them in a worker.

// type signature
(node: IAnyStateTreeNode) => PaletteHost

Source code

getRenderingServices#

Everything a display needs of its host in order to draw a region: the assemblies, the RPC entry point and the colors.

// type signature
(node: IAnyStateTreeNode) => RenderingServices

Source code

getRpcHost#

The host's RPC entry point, for a module that issues RPCs and nothing else.

// type signature
(node: IAnyStateTreeNode) => RpcHost

Source code

getSession#

Returns the JBrowse session model for any node in the state tree. Throws if the node has no session ancestor.

// type signature
(node: IAnyStateTreeNode) => AbstractSessionModel

Source code

getSessionServices#

The services a session offers that cost nothing application-shaped to name. Prefer one of the narrower accessors below, which say which of them the calling module actually uses.

// type signature
(node: IAnyStateTreeNode) => SessionServices

Source code

launchOrReplaceView#

addOrReplaceView for view types whose state model may be lazily loaded; the synchronous addOrReplaceView requires it loaded already.

// type signature
(args: { session: AbstractViewContainer; typeName: string; initialState?: Record<string, unknown> | undefined; replacing?: AbstractViewModel | undefined; }) => Promise<...>

Source code

reservedPx#

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

// type signature
(band: Band) => number

Source code

runLazyAfterAttach#

Run a display's afterAttach body from a module loaded on demand, so the autorun installers stay out of the display's eager bundle.

One policy for the gap the await opens: a node torn down before the module lands installs nothing, and a module that fails to load is reported where the user can see it rather than onto the display's own error slot — that slot is what reload() clears, and nothing would re-run the install behind it. Three displays hand-rolled this IIFE and each drew the lines differently.

// type signature
<Self extends IStateTreeNode>(self: Self, load: () => Promise<(self: Self) => void>) => void

Source code

stackBands#

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 call this function, so the reserved and painted positions cannot disagree.

Only the fold is shared; the rest stays in each display. 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.

// type signature
<K extends string>(order: readonly K[], bands: Record<K, Band>) => BandStack<K>

Source code