@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/getFileName.js

@@ -0,0 +1,34 @@
+// Handles both forward slashes and Windows backslashes in file:// URLs
+function filenameFromPath(path) {
+    return path.replaceAll('\\', '/').split('/').at(-1) ?? '';
+}
+// A query string is a request parameter, not part of the name: a presigned S3 or
+// GCS link ends in a few hundred characters of `?X-Amz-Signature=...`, and every
+// caller here either shows the name to someone or matches an extension against
+// the end of it. Stripped for a URI only — `?` is a legal character in a POSIX
+// filename, so a local path keeps whatever it was given.
+function withoutQuery(filename) {
+    return filename.split(/[?#]/)[0];
+}
+/**
+ * The bare filename a location refers to, for every location type — a Blob and
+ * a FileHandle carry their name directly, a URI and a local path carry it as the
+ * last path segment.
+ *
+ * Its own module rather than living in `tracks.ts` because the assembly form
+ * helpers need it too, and `tracks.ts` pulls in MST and the configuration
+ * system. Re-exported from `tracks.ts`, which is the import path plugins use.
+ */
+export function getFileName(location) {
+    switch (location.locationType) {
+        case 'BlobLocation':
+        case 'FileHandleLocation':
+            return location.name;
+        case 'UriLocation':
+            return withoutQuery(filenameFromPath(location.uri));
+        case 'LocalPathLocation':
+            return filenameFromPath(location.localPath);
+        default:
+            return '';
+    }
+}

package/esm/util/getLocationUri.d.ts

@@ -0,0 +1,49 @@
+import type { FileLocation } from './types/data.ts';
+/**
+ * A `UriLocation` as the absolute address it actually fetches — its `uri`
+ * resolved against `baseUri`, so a config's relative path reads as the URL the
+ * network saw rather than the fragment the config held.
+ */
+export declare function resolveUri({ uri, baseUri, }: {
+    uri: string;
+    baseUri?: string;
+}): string;
+/**
+ * An address with its query string dropped, which is what makes it safe to put
+ * on screen. A presigned S3 or GCS link carries its credential in the query — a
+ * few hundred characters of `?X-Amz-Signature=…` — and a notice that renders one
+ * puts it in front of whoever is looking at the screen and into every screenshot
+ * of it. The host and path are the whole diagnostic anyway.
+ *
+ * Same reasoning as {@link getFileName}'s own strip. A URL only: `?` is a legal
+ * character in a POSIX filename, so a path keeps whatever it was given, and a
+ * scheme is what tells the two apart when the caller has a bare string rather
+ * than a typed location.
+ */
+export declare function redactSource(source: string): string;
+/**
+ * Where a location's bytes come from, as an address worth showing someone, or
+ * undefined when it has none.
+ *
+ * "None" is the honest answer for a Blob and a FileHandle: they are bytes the
+ * user handed the page, with no address to go and check. It is the answer a
+ * stalled-load notice needs — the notice exists to name a server that stopped
+ * answering, and there is no server behind either of those.
+ */
+export declare function getLocationUri(location: FileLocation): string | undefined;
+/**
+ * A download phase that names the file it is fetching, for the stalled-load
+ * notice — a source-carrying phase when the location has an address to show, and
+ * the bare label when it does not, which is the same thing the phase helpers
+ * always took.
+ *
+ * **Only for a read this process does not perform.** Anything going through
+ * `fetchAndMaybeUnzip` takes its source off the filehandle and needs none of
+ * this; what is left is the readers that open a handle and then do their own
+ * reads through it — `@gmod/twobit` and `@gmod/indexedfasta` — where the phase
+ * has to be built from the config the handle was opened from instead.
+ */
+export declare function downloadPhase(message: string, location: FileLocation): string | {
+    message: string;
+    source: string;
+};

package/esm/util/getLocationUri.js

@@ -0,0 +1,63 @@
+import { isLocalPathLocation, isUriLocation } from './types/data.js';
+/**
+ * A `UriLocation` as the absolute address it actually fetches — its `uri`
+ * resolved against `baseUri`, so a config's relative path reads as the URL the
+ * network saw rather than the fragment the config held.
+ */
+export function resolveUri({ uri, baseUri = '', }) {
+    try {
+        return new URL(uri, baseUri).href;
+    }
+    catch {
+        return uri;
+    }
+}
+/**
+ * An address with its query string dropped, which is what makes it safe to put
+ * on screen. A presigned S3 or GCS link carries its credential in the query — a
+ * few hundred characters of `?X-Amz-Signature=…` — and a notice that renders one
+ * puts it in front of whoever is looking at the screen and into every screenshot
+ * of it. The host and path are the whole diagnostic anyway.
+ *
+ * Same reasoning as {@link getFileName}'s own strip. A URL only: `?` is a legal
+ * character in a POSIX filename, so a path keeps whatever it was given, and a
+ * scheme is what tells the two apart when the caller has a bare string rather
+ * than a typed location.
+ */
+export function redactSource(source) {
+    return source.includes('://') ? source.split(/[?#]/)[0] : source;
+}
+/**
+ * Where a location's bytes come from, as an address worth showing someone, or
+ * undefined when it has none.
+ *
+ * "None" is the honest answer for a Blob and a FileHandle: they are bytes the
+ * user handed the page, with no address to go and check. It is the answer a
+ * stalled-load notice needs — the notice exists to name a server that stopped
+ * answering, and there is no server behind either of those.
+ */
+export function getLocationUri(location) {
+    if (isUriLocation(location)) {
+        return redactSource(resolveUri(location));
+    }
+    if (isLocalPathLocation(location)) {
+        return location.localPath;
+    }
+    return undefined;
+}
+/**
+ * A download phase that names the file it is fetching, for the stalled-load
+ * notice — a source-carrying phase when the location has an address to show, and
+ * the bare label when it does not, which is the same thing the phase helpers
+ * always took.
+ *
+ * **Only for a read this process does not perform.** Anything going through
+ * `fetchAndMaybeUnzip` takes its source off the filehandle and needs none of
+ * this; what is left is the readers that open a handle and then do their own
+ * reads through it — `@gmod/twobit` and `@gmod/indexedfasta` — where the phase
+ * has to be built from the config the handle was opened from instead.
+ */
+export function downloadPhase(message, location) {
+    const source = getLocationUri(location);
+    return source === undefined ? message : { message, source };
+}

package/esm/util/getRelativeX.d.ts

@@ -0,0 +1,4 @@
+export declare function getRelativeX(event: {
+    clientX: number;
+    target: EventTarget | null;
+}, element: HTMLElement | null): number;

package/esm/util/getRelativeX.js

@@ -0,0 +1,7 @@
+// Against an element handed in, deliberately: a rubberband drag tracks the
+// pointer across the whole document, so the box it projects through is the one
+// it started in and not whatever the cursor is now over. For the ordinary case —
+// a handler measuring against its own element — see `eventPoint`.
+export function getRelativeX(event, element) {
+    return event.clientX - (element?.getBoundingClientRect().left ?? 0);
+}

package/esm/util/getStr.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A value rendered as a display string: a UriLocation as its resolved href, any
+ * other object as JSON, everything else via String(). Shared by the DataGrid
+ * column-width heuristic and the feature-detail panels.
+ */
+export declare function getStr(obj: unknown): string;

package/esm/util/getStr.js

@@ -0,0 +1,15 @@
+import { resolveUri } from './getLocationUri.js';
+import { isObject } from './objectUtils.js';
+import { isUriLocation } from './types/data.js';
+/**
+ * A value rendered as a display string: a UriLocation as its resolved href, any
+ * other object as JSON, everything else via String(). Shared by the DataGrid
+ * column-width heuristic and the feature-detail panels.
+ */
+export function getStr(obj) {
+    return isObject(obj)
+        ? isUriLocation(obj)
+            ? resolveUri(obj)
+            : JSON.stringify(obj)
+        : String(obj);
+}

package/esm/util/groupKeys.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The ordering every in-track group-by shares, whatever partitioned the
+ * features: named groups first, then the `''` catch-all a dimension files its
+ * unanswerable features under, then the overflow bucket a capped partition
+ * merged its tail into.
+ */
+export declare const OVERFLOW_GROUP_KEY = "\0overflow";
+export declare const MAX_GROUPS = 40;
+/**
+ * The text a field value groups, colors and labels by: a missing value is the
+ * `''` catch-all, a VCF's `.` among them, which `@gmod/vcf` hands over as
+ * `[undefined]`, and a multi-valued attribute joins, so two features carrying
+ * the same list land together.
+ */
+export declare function valueText(value: unknown): string;
+/**
+ * Numbers first by value, then every other key run by run with digit runs by
+ * magnitude, so -1 before 1 and chr2 before chr10. The two classes never
+ * interleave: a signed or decimal number read run by run orders differently
+ * than by value, and letting them mix made the order intransitive.
+ */
+export declare function compareGroupKeys(a: string, b: string): number;
+/**
+ * The order a facet stacks its sections in. `domain` is the channel's
+ * declared order: the keys it lists come first, in that order, and the rest
+ * follow under `compareGroupKeys`. Every categorical channel in the tree
+ * reads its domain this way, so a listed value is a placement and an
+ * unlisted one is not an error.
+ */
+export declare function groupKeyComparator(domain?: readonly string[]): typeof compareGroupKeys;
+/**
+ * The domain a re-pick keeps: a facet set from a menu or dialog names no
+ * domain, so one naming the field the current facet already reads carries
+ * the current order along. A reorder names its own domain and passes
+ * through, an empty one included.
+ */
+export declare function carryGroupDomain<T extends {
+    field: string;
+    domain?: readonly string[];
+}>(next: T | undefined, current: T | undefined): T | undefined;
+/**
+ * The overflow bucket's chip. Says MERGED because that lane is the one entry
+ * in a stack that is not a value, and this label is the only place a reader
+ * is told the cap fired at all.
+ */
+export declare function overflowLabel(count: number): string;
+/**
+ * Which section each key stacks into once the cap applies: the first
+ * `limit` keys (`MAX_GROUPS` by default) in natural order keep their own and
+ * the rest fold into the overflow section; `Infinity` folds none. The
+ * catch-all `''` is held out of the merge, since "lacking the value" is an
+ * answer users look for. A domain orders the
+ * sections and never decides which exist, so reordering them changes no
+ * key's section.
+ */
+export declare function capGroupKeys(keys: Iterable<string>, limit?: number): {
+    mergedCount: number;
+    sectionOf: (key: string) => string;
+};
+/**
+ * A group's stable identity: its sort key and the label its chip shows.
+ */
+export interface GroupId {
+    key: string;
+    label: string;
+}
+/**
+ * Identity of the key space a facet hands out keys in: its field. A key means
+ * nothing on its own, since `''` is both the ungrouped section and every
+ * field's catch-all, so anything keyed by group key is dropped when this
+ * moves. The `domain` only orders the keys and is no part of the space, so a
+ * reorder keeps what a reader hid.
+ */
+export declare function groupKeySpaceOf(facet: {
+    field: string;
+    domain?: readonly string[];
+} | undefined): string;

package/esm/util/groupKeys.js

@@ -0,0 +1,155 @@
+/**
+ * The ordering every in-track group-by shares, whatever partitioned the
+ * features: named groups first, then the `''` catch-all a dimension files its
+ * unanswerable features under, then the overflow bucket a capped partition
+ * merged its tail into.
+ */
+// '\0' cannot collide with a real tag value or refName, and the rank below
+// pins it dead last so a merged tail never displaces a named group.
+export const OVERFLOW_GROUP_KEY = '\u0000overflow';
+// Hard ceiling on the sections one grouping may stack; the tail past it merges
+// into the overflow section. A backstop for the dimensions that are not a
+// closed set, a tag or an attribute, whose value space is the file's.
+export const MAX_GROUPS = 40;
+/**
+ * The text a field value groups, colors and labels by: a missing value is the
+ * `''` catch-all, a VCF's `.` among them, which `@gmod/vcf` hands over as
+ * `[undefined]`, and a multi-valued attribute joins, so two features carrying
+ * the same list land together.
+ */
+export function valueText(value) {
+    return value === undefined || value === null
+        ? ''
+        : Array.isArray(value)
+            ? value
+                .filter(v => v !== undefined && v !== null)
+                .map(String)
+                .join(',')
+            : String(value);
+}
+function groupKeyRank(key) {
+    return key === '' ? 1 : key === OVERFLOW_GROUP_KEY ? 2 : 0;
+}
+const NUMERIC = /^-?\d+(\.\d+)?$/;
+const DIGIT_RUNS = /\d+|\D+/g;
+function compareRuns(a, b) {
+    const runsA = a.match(DIGIT_RUNS) ?? [];
+    const runsB = b.match(DIGIT_RUNS) ?? [];
+    const shared = Math.min(runsA.length, runsB.length);
+    for (let i = 0; i < shared; i++) {
+        const x = runsA[i];
+        const y = runsB[i];
+        if (x === y) {
+            continue;
+        }
+        if (/^\d/.test(x) && /^\d/.test(y)) {
+            const nx = Number(x);
+            const ny = Number(y);
+            if (nx !== ny) {
+                return nx < ny ? -1 : 1;
+            }
+            return x.length < y.length ? -1 : 1;
+        }
+        return x < y ? -1 : 1;
+    }
+    return runsA.length - runsB.length;
+}
+/**
+ * Numbers first by value, then every other key run by run with digit runs by
+ * magnitude, so -1 before 1 and chr2 before chr10. The two classes never
+ * interleave: a signed or decimal number read run by run orders differently
+ * than by value, and letting them mix made the order intransitive.
+ */
+export function compareGroupKeys(a, b) {
+    const rankDiff = groupKeyRank(a) - groupKeyRank(b);
+    if (rankDiff !== 0 || a === b) {
+        return rankDiff;
+    }
+    const numA = NUMERIC.test(a);
+    const numB = NUMERIC.test(b);
+    if (numA !== numB) {
+        return numA ? -1 : 1;
+    }
+    if (numA) {
+        const diff = Number(a) - Number(b);
+        if (diff !== 0) {
+            return diff < 0 ? -1 : 1;
+        }
+    }
+    return compareRuns(a, b);
+}
+/**
+ * The order a facet stacks its sections in. `domain` is the channel's
+ * declared order: the keys it lists come first, in that order, and the rest
+ * follow under `compareGroupKeys`. Every categorical channel in the tree
+ * reads its domain this way, so a listed value is a placement and an
+ * unlisted one is not an error.
+ */
+export function groupKeyComparator(domain) {
+    if (!domain?.length) {
+        return compareGroupKeys;
+    }
+    const rank = new Map();
+    domain.forEach((key, i) => {
+        if (!rank.has(key)) {
+            rank.set(key, i);
+        }
+    });
+    return (a, b) => {
+        const ra = rank.get(a) ?? Infinity;
+        const rb = rank.get(b) ?? Infinity;
+        return ra !== rb ? (ra < rb ? -1 : 1) : compareGroupKeys(a, b);
+    };
+}
+/**
+ * The domain a re-pick keeps: a facet set from a menu or dialog names no
+ * domain, so one naming the field the current facet already reads carries
+ * the current order along. A reorder names its own domain and passes
+ * through, an empty one included.
+ */
+export function carryGroupDomain(next, current) {
+    return next !== undefined &&
+        next.domain === undefined &&
+        current?.domain !== undefined &&
+        next.field === current.field
+        ? { ...next, domain: current.domain }
+        : next;
+}
+/**
+ * The overflow bucket's chip. Says MERGED because that lane is the one entry
+ * in a stack that is not a value, and this label is the only place a reader
+ * is told the cap fired at all.
+ */
+export function overflowLabel(count) {
+    return `${count} merged values`;
+}
+/**
+ * Which section each key stacks into once the cap applies: the first
+ * `limit` keys (`MAX_GROUPS` by default) in natural order keep their own and
+ * the rest fold into the overflow section; `Infinity` folds none. The
+ * catch-all `''` is held out of the merge, since "lacking the value" is an
+ * answer users look for. A domain orders the
+ * sections and never decides which exist, so reordering them changes no
+ * key's section.
+ */
+export function capGroupKeys(keys, limit = MAX_GROUPS) {
+    const ordered = [...new Set(keys)].sort(compareGroupKeys);
+    const hasUntagged = ordered.includes('');
+    const named = ordered.filter(key => key !== '');
+    const merged = ordered.length > limit ? named.slice(limit - (hasUntagged ? 2 : 1)) : [];
+    const mergedSet = new Set(merged);
+    return {
+        mergedCount: merged.length,
+        sectionOf: (key) => (mergedSet.has(key) ? OVERFLOW_GROUP_KEY : key),
+    };
+}
+/**
+ * Identity of the key space a facet hands out keys in: its field. A key means
+ * nothing on its own, since `''` is both the ungrouped section and every
+ * field's catch-all, so anything keyed by group key is dropped when this
+ * moves. The `domain` only orders the keys and is no part of the space, so a
+ * reorder keeps what a reader hid.
+ */
+export function groupKeySpaceOf(facet) {
+    return facet?.field ?? '';
+}

package/esm/util/highlights.d.ts

@@ -0,0 +1,25 @@
+import type { JBrowsePalette } from '../ui/palette.ts';
+export interface HighlightType {
+    start: number;
+    end: number;
+    assemblyName: string;
+    refName: string;
+    color?: string;
+    label?: string;
+}
+export type HighlightInput = Omit<HighlightType, 'assemblyName'> & {
+    assemblyName?: string;
+};
+export declare function isSameHighlight(a: HighlightType, b: HighlightType): boolean;
+export declare function highlightKey(h: {
+    assemblyName?: string;
+    refName: string;
+    start: number;
+    end: number;
+}, i: number): string;
+export declare function getHighlightColor(highlight: {
+    color?: string;
+}, theme: {
+    palette: Pick<JBrowsePalette, 'highlight'>;
+}, alpha?: number): import("./colord.ts").Colord;
+export declare function coerceHighlight(h: string | HighlightInput, defaultAssembly: string, isValidRefName: (refName: string, assemblyName?: string) => boolean): HighlightType | undefined;

package/esm/util/highlights.js

@@ -0,0 +1,87 @@
+import { colord } from './colord.js';
+import { parseLocString } from './locString.js';
+export function isSameHighlight(a, b) {
+    return (a.assemblyName === b.assemblyName &&
+        a.refName === b.refName &&
+        a.start === b.start &&
+        a.end === b.end &&
+        a.color === b.color &&
+        a.label === b.label);
+}
+// Highlight regions have no id and can duplicate, so the trailing index only
+// breaks ties between otherwise-identical regions. Wrapping the array index in
+// this helper also keeps it out of the `no-array-index-key` lint's view.
+// JSON-encoding the fields (rather than joining on a delimiter) avoids
+// collisions when a refName contains the delimiter, e.g. `chr1_2`@3 vs
+// `chr1`@`2_3`.
+export function highlightKey(h, i) {
+    return JSON.stringify([h.assemblyName, h.refName, h.start, h.end, i]);
+}
+// User-supplied color is used as-is so explicit alpha is preserved; otherwise
+// fall back to the theme highlight color at the given alpha. Shared by the LGV
+// and dotplot highlight bands (which differ only in their default alpha).
+export function getHighlightColor(highlight, theme, alpha = 0.2) {
+    return highlight.color
+        ? colord(highlight.color)
+        : colord(theme.palette.highlight.main).alpha(alpha);
+}
+function tryParseJson(s) {
+    try {
+        const v = JSON.parse(s);
+        return v && typeof v === 'object'
+            ? v
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+// a string is either a loc string ("chr1:100-200") or a JSON-encoded
+// HighlightType (the URL wire-format, since URL params can't carry objects).
+// note: the jbrowse-web &highlight= URL param is space-split, so the JSON-string
+// form only survives when it contains no spaces; a label with a space is
+// shattered by the split — pass a HighlightType object instead
+function parseJsonHighlight(s, defaultAssembly) {
+    const json = s.trimStart().startsWith('{') ? tryParseJson(s) : undefined;
+    return json &&
+        typeof json.refName === 'string' &&
+        typeof json.start === 'number' &&
+        typeof json.end === 'number'
+        ? {
+            refName: json.refName,
+            start: json.start,
+            end: json.end,
+            assemblyName: typeof json.assemblyName === 'string'
+                ? json.assemblyName
+                : defaultAssembly,
+            color: typeof json.color === 'string' ? json.color : undefined,
+            label: typeof json.label === 'string' ? json.label : undefined,
+        }
+        : undefined;
+}
+// The `{assembly}` prefix a locstring may carry is kept, not overwritten with
+// the default: on a dotplot the two axes are two different assemblies, so
+// `{mm10}chr1:1-100` stamped with the horizontal axis' assembly drew the band on
+// the wrong axis (see DotplotView's axisHighlightRegion, which routes by exactly
+// this field) with nothing said. Single-assembly views are unaffected — their
+// only prefix is the default anyway.
+function parseLocHighlight(s, defaultAssembly, isValidRefName) {
+    const { assemblyName, refName, start, end } = parseLocString(s, isValidRefName);
+    return start !== undefined && end !== undefined
+        ? { refName, start, end, assemblyName: assemblyName ?? defaultAssembly }
+        : undefined;
+}
+// Normalize a launch spec's `highlight` entry (object, JSON string, or loc
+// string) into a HighlightType, defaulting the assemblyName. Shared by
+// LinearGenomeView and DotplotView, whose `highlight` launch keys accept the
+// same three forms — the JSON shape-check in particular has to stay identical or
+// a highlight that works in one view silently drops in the other.
+export function coerceHighlight(h, defaultAssembly, 
+// takes the assembly a `{...}` prefix named, so a caller with more than one
+// assembly in play validates the refName against the one the entry asked for
+isValidRefName) {
+    return typeof h === 'object'
+        ? { ...h, assemblyName: h.assemblyName ?? defaultAssembly }
+        : (parseJsonHighlight(h, defaultAssembly) ??
+            parseLocHighlight(h, defaultAssembly, isValidRefName));
+}