@jbrowse/plugin-linear-genome-view 4.3.0 → 5.0.0-beta.10

package/esm/LinearGenomeView/util.d.ts

@@ -1,30 +1,365 @@
 import type { AssemblyManager, ParsedLocString } from '@jbrowse/core/util';
-import type { BaseBlock } from '@jbrowse/core/util/blockTypes';
+import type { PxToBpResult } from '@jbrowse/core/util/Base1DUtils';
+import type { BaseBlock, ContentBlock } from '@jbrowse/core/util/blockTypes';
+import type { Region } from '@jbrowse/core/util/types';
+interface CenterKeepingView {
+    width: number;
+    displayedRegions: Region[];
+    pxToBp: (px: number) => PxToBpResult;
+    setDisplayedRegions: (regions: Region[]) => void;
+    centerAt: (coord: number, refName: string, index?: number) => void;
+}
+/**
+ * The stored viewport of a view showing `totalBp` of displayed regions fitted to
+ * `width` — the regions filling it edge to edge, and centered in it only where
+ * they are too narrow to fill it.
+ *
+ * **This is where the fit-to-width rule is written.** `fitAllRegions` takes its
+ * scale from here rather than restating it, so the two cannot drift; a second
+ * spelling of `max(minBpPerPx * width, totalBp)` reading `MIN_BP_PER_PX` where
+ * the action reads the `minBpPerPx` GETTER would agree only for as long as
+ * nothing overrides it.
+ *
+ * The reason it is a function at all is `windowStartBp`, which `fitAllRegions`
+ * does not need (it centers in pixels, through `scrollTo`, which also clamps).
+ * A caller building a view SNAPSHOT does: it has no model to call
+ * `fitAllRegions()` on, and naming `bpPerPx`/`offsetPx` instead is dropped
+ * whenever the snapshot also carries a `windowWidthBp` — which one copied off an
+ * existing view always does. plugin-canvas's collapsed-intron launch is that
+ * caller. A live view calls `fitAllRegions()`.
+ *
+ * `width` enters only through the zoom-in floor, which bites for a region set
+ * narrower than `width * minBpPerPx`; the window itself is in bp and needs no
+ * width, which is why a snapshot can carry it at all.
+ */
+export declare function fitAllRegionsWindow(totalBp: number, width: number, minBpPerPx: number): {
+    windowWidthBp: number;
+    windowStartBp: number;
+};
+/**
+ * Expand a region by a grow factor, adding padding on each side.
+ *
+ * @param start - region start coordinate
+ * @param end - region end coordinate
+ * @param grow - multiplier for expansion (e.g., 0.2 adds 20% padding on each
+ * side)
+ * @param minBound - minimum bound to clamp start to (default 0)
+ * @param maxBound - maximum bound to clamp end to (default Infinity)
+ * @returns object with expanded start and end coordinates
+ */
 export declare function expandRegion(start: number, end: number, grow: number, minBound?: number, maxBound?: number): {
     start: number;
     end: number;
 };
-export declare function chooseGridPitch(scale: number, minMajorPitchPx: number, minMinorPitchPx: number): {
-    majorPitch: number;
-    minorPitch: number;
+/**
+ * Generate tick positions for the overview scalebar. Anchors at the first neat
+ * majorPitch multiple strictly inside the block so ticks land on round numbers
+ * regardless of where the block starts/ends.
+ */
+export declare function makeOverviewTicks(start: number, end: number, bpPerPx: number, reversed?: boolean): {
+    genomicCoord: number;
+    offsetPx: number;
+}[];
+export interface Tick {
+    type: 'major' | 'minor';
+    base: number;
+}
+/**
+ * Ticks for one span of the ruler. Not the dotplot's same-named function, which
+ * walks static blocks into a single continuous axis and therefore has to dedupe
+ * the shared block seam and carry each tick's px. Here every block draws its own
+ * clipped ruler, so this overscans its span instead of deduping and leaves px to
+ * `makeBlockTicks`. What the two do share is already shared: `chooseGridPitch`,
+ * and `base` as the 0-based coordinate that `getTickDisplayStr` labels `base+1`.
+ */
+export declare function makeTicks(start: number, end: number, bpPerPx: number, includeMinor?: boolean): Tick[];
+/** A block's refName, or undefined for non-content (elided/padding) blocks. */
+export declare function getBlockRefName(block: BaseBlock): string | undefined;
+/**
+ * For blocks in display order, returns whether each block's refName should be
+ * labeled: true only for the first block of each run of same-refName regions,
+ * so a refName is shown once instead of repeated at every region boundary (e.g.
+ * collapsed introns produce many adjacent same-refName regions).
+ *
+ * A block with no refName ends the run. What an elided block hides is *other
+ * chromosomes*, so the same name reappearing on its far side starts a region the
+ * reader needs named again, not a continuation of the one before it. Regions lay
+ * out contiguously, so an elided run is the only nameless block that can fall
+ * between two content blocks — the boundary pads only bracket the whole set,
+ * where ending a run changes nothing.
+ */
+export declare function showRefNameLabels<T>(blocks: T[], getRefName: (block: T) => string | undefined): boolean[];
+/**
+ * Whether the displayed regions are laid out left-to-right, right-to-left, or
+ * some of each. `horizontallyFlip` reverses the order and flips every region at
+ * once, so a flipped row is uniformly `reversed`; `mixed` takes going out of
+ * your way, through the scalebar label menu's per-region "Reverse region".
+ */
+export type RegionsOrientation = 'forward' | 'reversed' | 'mixed';
+export declare function regionsOrientation(regions: {
+    reversed?: boolean;
+}[]): RegionsOrientation;
+export interface ScalebarRefNameLabel {
+    key: string;
+    refName: string;
+    displayedRegionIndex: number;
+    lastDisplayedRegionIndex: number;
+    sticky: boolean;
+    transform: number;
+    maxWidth: number;
+    paddingLeft: number;
+    text: string;
+}
+/**
+ * Builds the refName labels drawn along the scalebar as plain data (no JSX): one
+ * label per run of same-refName regions, the leftmost of them "sticky" — pinned
+ * so the run under the left edge stays named once its own left edge scrolls off.
+ *
+ * `caption` is the row-level chip at the viewport's left edge: which assembly
+ * the row is (`prefix`, synteny only) and whether the whole row is flipped. The
+ * chip takes `captionSpanPx` of the strip and the labels get the rest, so the
+ * sticky label pins to the chip's right edge ("hg38" then "chr1") and rides the
+ * run under THAT edge. A run the chip covers entirely goes unnamed, and the
+ * chip is not shortened to uncover it: a width fitted to the run under it
+ * changes with every run that pans past, and a fixed cap short enough to
+ * uncover a 55px chromosome cuts ordinary names. The assembly's `displayName`
+ * is where a long name gets shortened.
+ *
+ * `orientation` decides the ` [rev]` marker, following `assembleLocStrings`: say
+ * it where it distinguishes, once where it does not.
+ *
+ * - `reversed`: the caption carries the marker and no name does. A marker on a
+ *   chromosome name is how the mixed case flags that one region.
+ * - `mixed`: every reversed run is marked. A marked label that fails the fit
+ *   test falls back to the bare name rather than dropping.
+ * - `forward`: no marker.
+ *
+ * `maxWidth` is the whole label box, `paddingLeft` included — both consumers
+ * clip from the box's left edge. A name is drawn whole or not at all: clipped
+ * mid-glyph, "chr16" reads as "chr1".
+ */
+export declare function getScalebarRefNameLabels({ blocks, offsetPx, prefix, orientation, }: {
+    blocks: BaseBlock[];
+    offsetPx: number;
+    prefix: string | undefined;
+    orientation?: RegionsOrientation;
+}): {
+    labels: ScalebarRefNameLabel[];
+    caption: string | undefined;
+    captionSpanPx: number;
+};
+/**
+ * Screen-x span a refName label paints over: its padding and its glyphs, which
+ * is the whole of it, since the box shrinks to its text rather than filling the
+ * `maxWidth` it was fitted against. Anything drawn under this span is hidden by
+ * the label's opaque backing, so the coordinate numbers use it to stay out from
+ * under the sticky label the way `runRefNameLabelPx` keeps them out from under
+ * the others.
+ */
+export declare function refNameLabelSpanPx(label: ScalebarRefNameLabel): {
+    left: number;
+    right: number;
 };
-export declare function makeTicks(start: number, end: number, bpPerPx: number, emitMajor?: boolean, emitMinor?: boolean): {
-    type: string;
+/**
+ * Whether a label from getScalebarRefNameLabels is drawn whole within a
+ * viewport `widthPx` wide. The labels themselves are only fitted to their own
+ * *run of regions*, which routinely runs past the right edge of the view, so
+ * one starting a few px before that edge passes the run fit and is then cut by
+ * the viewport clip. On screen that reads as a name scrolled partly out of
+ * frame, but a static SVG export has no frame to scroll — there a cut "LG2"
+ * just names a chromosome that doesn't exist, so the export drops it instead,
+ * as it already does for tick numbers at the same edge.
+ */
+export declare function refNameLabelFitsInView(label: ScalebarRefNameLabel, widthPx: number): boolean;
+/**
+ * The reorder entries the refName-label menu offers for the region at `idx` of
+ * `numRegions`, each already carrying the index it moves to. The "far" moves
+ * need a gap of more than one between `idx` and the end — otherwise "Move to
+ * far left/right" targets the same index as "Move left/right" and duplicates
+ * the entry.
+ */
+export declare function regionMoveActions(idx: number, numRegions: number): {
+    label: string;
+    to: number;
+}[];
+/**
+ * A new region list, and where each old index went in it (-1 for a region it
+ * dropped). The index map is what lets a region displayed twice be followed.
+ */
+export interface RegionEdit {
+    regions: Region[];
+    newIndexOf: (oldIndex: number) => number;
+}
+export declare function withRegionMoved(regions: Region[], from: number, to: number): RegionEdit;
+export declare function withRegionRemoved(regions: Region[], index: number): RegionEdit;
+export declare function withRegionsKept(regions: Region[], first: number, last: number): RegionEdit;
+export declare function withRegionReversed(regions: Region[], index: number): RegionEdit;
+/**
+ * Apply a region edit and keep the base under the middle of the viewport
+ * there, where the edit kept its region. `setDisplayedRegions` alone carries
+ * `offsetPx` into a coordinate space the edit redefined, which lands on
+ * whatever region now sits at that offset.
+ */
+export declare function setDisplayedRegionsKeepingCenter(model: CenterKeepingView, { regions, newIndexOf }: RegionEdit): void;
+/**
+ * The full run of same-orientation regions on one refName that a scalebar
+ * label's `firstRegionIndex`..`lastRegionIndex` sits inside. Those come off the
+ * static blocks, which are clipped to the viewport and broken by an elided
+ * block, so a zoomed-in collapsed-introns view brackets only the exons on
+ * screen — which is the wrong answer for anything acting on the whole run.
+ */
+export declare function regionRunBounds(regions: Region[], firstIndex: number, lastIndex: number): {
+    first: number;
+    last: number;
+};
+/**
+ * Whether a label occupying [leftPx, leftPx + labelWidth] fits within a block
+ * of the given pixel width, used to skip tick labels that would be clipped at a
+ * region edge (common with small collapsed-intron regions).
+ */
+export declare function labelFitsInBlock(leftPx: number, labelWidth: number, widthPx: number): boolean;
+/** Font size of coordinate tick labels on the scalebar and overview scalebar. */
+export declare const TICK_LABEL_FONT_SIZE = 11;
+/**
+ * On-screen width of a coordinate tick label: the text plus 2px of horizontal
+ * padding on each side. Single-sourced so the HTML scalebar and the SVG export
+ * agree on when a label is too wide to fit inside its block.
+ */
+export declare function tickLabelWidth(label: string): number;
+/** Font size of the bold refName label drawn at the left edge of its block, on
+ * the scalebar and the overview scalebar alike. */
+export declare const REF_NAME_LABEL_FONT_SIZE = 11;
+/**
+ * Horizontal space the overview refName label occupies at a block's left edge.
+ * Overview tick labels use this to avoid drawing underneath the refName, which
+ * otherwise collide when zoomed far out (ticks bunch up near the block start).
+ */
+export declare function overviewRefNameLabelWidth(refName: string): number;
+/**
+ * How far right the ideogram starts, i.e. the gutter the chromosome name drawn
+ * to its left gets to itself. Shares overviewRefNameLabelWidth with the tick
+ * labels that dodge the same name, rather than measuring it again at a font size
+ * (12) the label is not actually drawn at (REF_NAME_LABEL_FONT_SIZE).
+ */
+export declare function cytobandLabelGutterWidth(refName: string): number;
+/**
+ * Coordinate labels drawn inside one overview-scalebar block: tick text plus its
+ * x within the block. Labels that can't be drawn whole between the block's bold
+ * refName label and its right edge are dropped by the same
+ * tickLabelWidth/labelFitsInBlock test the main scalebar and SVG export use; if
+ * too few survive to make a ruler, the block goes unnumbered.
+ */
+export declare function makeOverviewTickLabels({ block, bpPerPx, refNameLabelPx, }: {
+    block: {
+        start: number;
+        end: number;
+        reversed?: boolean;
+        widthPx: number;
+    };
+    bpPerPx: number;
+    refNameLabelPx: number;
+}): {
+    genomicCoord: number;
+    offsetPx: number;
+    label: string;
+}[];
+/**
+ * A maximal run of adjacent staticBlocks that belong to one contiguous
+ * displayed region. staticBlocks chop a region into ~800px chunks; merging them
+ * back means a coordinate label sitting on an internal chunk boundary is no
+ * longer clipped away by both neighbors (only genuine region edges clip).
+ */
+export interface BlockRun {
+    offsetPx: number;
+    widthPx: number;
+    start: number;
+    end: number;
+    reversed: boolean;
+    refName: string;
+    isLeftEndOfDisplayedRegion: boolean;
+    labeled: boolean;
+}
+export declare function groupContiguousBlocks(blocks: BaseBlock[]): BlockRun[];
+/**
+ * Horizontal space reserved at each run's left edge for the bold refName label
+ * drawn there, or 0 for runs that get none. Coordinate labels use this to stay
+ * out from under the name, the way the overview scalebar's already do via
+ * overviewRefNameLabelWidth: the refName label is opaque and painted after the
+ * numbers, so one underneath it isn't merely crowded but invisible — and since
+ * both sit in the block frame and scroll together, invisible at every scroll
+ * position rather than only while passing behind.
+ *
+ * Which runs get a label follows getScalebarRefNameLabels: only where a region
+ * genuinely begins, and only the first of a run of one refName (collapsed
+ * introns make many adjacent regions of the same name). It deliberately drops
+ * that function's offsetPx term so the reservation — and with it scalebarLabels
+ * — stays stable while scrolling; a run scrolled off the left reserves space
+ * that is off-screen anyway. Where the two disagree the reservation is the
+ * conservative side: at worst a coordinate is dropped from a region too narrow
+ * to have kept MIN_TICK_LABELS_PER_BLOCK of them.
+ *
+ * `orientation` enters because under `mixed` a reversed run's label carries the
+ * ` [rev]` marker and so is wider than its name. Under a uniformly `reversed`
+ * row only the sticky label is marked, and that one is dodged on screen instead
+ * (`refNameLabelSpanPx`), its x being a function of the scroll rather than of
+ * this frame.
+ */
+export declare function runRefNameLabelPx(runs: BlockRun[], orientation?: RegionsOrientation): number[];
+/**
+ * makeTicks plus each tick's pixel x within its block, accounting for reversed
+ * regions. Single source of the tick→px formula shared by gridlines, the
+ * scalebar coordinate labels, and SVG export so their positions can't drift.
+ */
+export declare function makeBlockTicks({ start, end, reversed, }: {
+    start: number;
+    end: number;
+    reversed?: boolean;
+}, bpPerPx: number, includeMinor?: boolean): {
+    type: 'major' | 'minor';
     base: number;
-    index: number;
+    x: number;
 }[];
+/**
+ * Generate location objects for a set of parsed locstrings, which includes
+ * translating the refNames to assembly-canonical refNames and adding the
+ * 'parentRegion'
+ *
+ * Used by navToLocations and navToLocString
+ *
+ * @param regions - array of parsed location strings to generate locations for
+ * @param assemblyManager - the assembly manager instance
+ * @param assemblyName - optional assembly name to use for regions that don't
+ * specify one
+ * @param grow - optional multiplier to expand regions by (e.g., 0.2 adds 20%
+ * padding on each side of the region). Useful for adding visual padding when
+ * navigating to a feature
+ */
 export declare function generateLocations({ regions, assemblyManager, assemblyName, grow, }: {
     regions: ParsedLocString[];
     assemblyManager: AssemblyManager;
     assemblyName?: string;
     grow?: number;
 }): Promise<{
-    assemblyName: string;
-    parentRegion: import("@jbrowse/core/assemblyManager/assembly").BasicRegion;
+    refName: string;
     start?: number;
     end?: number;
-    refName: string;
-    reversed?: boolean | undefined;
+    reversed?: boolean;
+    assemblyName: string;
+    parentRegion: import("@jbrowse/core/assemblyManager/assembly").BasicRegion;
 }[]>;
+/**
+ * Parses locString or space separated set of locStrings into location objects
+ * Example inputs:
+ * "chr1"
+ * "chr1:1-100"
+ * "chr1:1..100"
+ * "chr1 chr2"
+ * "chr1:1-100 chr2:1-100"
+ * "chr1 100 200" equivalent to "chr1:100-200"
+ * "chr1:34M-35M" equivalent to "chr1:34000000-35000000"
+ *
+ * Used by navToLocString
+ */
 export declare function parseLocStrings(input: string, assemblyName: string, isValidRefName: (str: string, assemblyName: string) => boolean): ParsedLocString[];
-export declare function calculateVisibleLocStrings(contentBlocks: BaseBlock[]): string;
+export declare function calculateVisibleLocStrings(contentBlocks: ContentBlock[]): string;
+export {};