@jbrowse/core 5.0.0-beta.1 → 5.0.0-beta.10

package/esm/util/binnedAggregate.js

@@ -0,0 +1,275 @@
+// The interval `bin` and the `aggregate` behind it as one kernel, which
+// `runSteps` in featureTransforms.ts reaches by relative path only.
+import { readerOf } from './featureTable.js';
+import { isPlainFieldRef } from './fieldReader.js';
+import { isJexl } from './jexlStrings.js';
+import { BIN_OVERLAP_FIELD, DEFAULT_BIN_AS, OpSums, binSize, groupKey, intervalsOf, isWeighted, madeGroups, stepNumberReader, } from './stepTables.js';
+/**
+ * The bin's edges and `overlap` a piece carries, where an `aggregate` reads a
+ * field off a piece: the row's own field where the bin wrote none. A later
+ * entry of the bin's written fields shadows an earlier one of the same name,
+ * as the piece table's columns do.
+ */
+const FROM_ROW = 0;
+const FROM_BIN_START = 1;
+const FROM_BIN_END = 2;
+const FROM_OVERLAP = 3;
+function pieceSource(field, [asStart, asEnd]) {
+    return field === BIN_OVERLAP_FIELD
+        ? FROM_OVERLAP
+        : field === asEnd
+            ? FROM_BIN_END
+            : field === asStart
+                ? FROM_BIN_START
+                : FROM_ROW;
+}
+function pick(source, row, lo, hi, overlap) {
+    return source === FROM_ROW
+        ? row
+        : source === FROM_BIN_START
+            ? lo
+            : source === FROM_BIN_END
+                ? hi
+                : overlap;
+}
+/**
+ * Whether an interval `bin` and the `aggregate` behind it run as one kernel:
+ * the aggregate groups by the bin's two edges, and every field it reads is a
+ * plain name, so a piece's value is its row's or one the bin wrote.
+ */
+export function fusesBinAggregate(bin, agg) {
+    const as = bin.as ?? DEFAULT_BIN_AS;
+    const groupby = agg.groupby ?? [];
+    const plain = (field) => field === undefined || (isPlainFieldRef(field) && !isJexl(field));
+    return (bin.fields !== undefined &&
+        as[0] !== as[1] &&
+        groupby.length === 2 &&
+        as.every(edge => groupby.includes(edge)) &&
+        as.every(plain) &&
+        agg.ops.every(op => plain(op.field) && plain(op.weight)));
+}
+// Beyond this many bins over the pieces a dense bin index costs more than the
+// pieces would, and the two steps run as written.
+const SPARSE_BINS_PER_PIECE = 2;
+const SPARSE_BINS_SLACK = 65536;
+/**
+ * An interval `bin` and the `aggregate` grouped by its edges as one walk: each
+ * row's bins accumulate straight into their group's sums, with no piece table,
+ * the way `binRawRegion` bins a BigWig's raw section. The groups come out in
+ * the order the pieces would have met them and each sum adds its pieces in
+ * the pieces' order, so the answer is the two steps' to the bit. Undefined
+ * where the bins spread too thinly over the region for a dense index.
+ */
+export function binnedAggregate({ table, bounds }, bin, agg) {
+    const size = binSize(bin);
+    const as = bin.as ?? DEFAULT_BIN_AS;
+    const iv = intervalsOf(table, bin.fields, size, bounds);
+    const { lowBin, highBin } = iv;
+    const sections = bounds.length - 1;
+    // Each section's bins from its lowest, at `offset[s]` in one index.
+    const offset = new Float64Array(sections + 1);
+    for (let s = 0; s < sections; s++) {
+        const span = highBin[s] - lowBin[s] + 1;
+        offset[s + 1] = offset[s] + (span > 0 ? span : 0);
+    }
+    const spans = offset[sections];
+    if (spans > SPARSE_BINS_PER_PIECE * iv.pieces + SPARSE_BINS_SLACK) {
+        return undefined;
+    }
+    const capacity = Math.min(spans, iv.pieces);
+    const groupOfBin = new Int32Array(spans).fill(-1);
+    const groupRow = new Uint32Array(capacity);
+    const groupBin = new Float64Array(capacity);
+    const groupSection = new Uint32Array(capacity);
+    const start = new Float64Array(capacity);
+    const end = new Float64Array(capacity);
+    const startSource = pieceSource('start', as);
+    const endSource = pieceSource('end', as);
+    // A group's extent is its bin's where the pieces' start and end are the
+    // bin's edges, the least and greatest of its pieces' otherwise.
+    const binExtent = startSource === FROM_BIN_START && endSource === FROM_BIN_END;
+    const readRowStart = readerOf(table.column('start'));
+    const readRowEnd = readerOf(table.column('end'));
+    const groups = numberGroups({ iv, bounds, size, lowBin, offset, groupOfBin }, { groupRow, groupBin, groupSection, start, end }, binExtent
+        ? undefined
+        : { startSource, endSource, readRowStart, readRowEnd });
+    const walk = { iv, bounds, size, lowBin, offset, groupOfBin };
+    const ops = agg.ops.map(op => {
+        const sums = new OpSums(op, groups);
+        const valueSource = op.op === 'count' || op.field === undefined
+            ? undefined
+            : pieceSource(op.field, as);
+        const weightSource = op.weight !== undefined && isWeighted(op)
+            ? pieceSource(op.weight, as)
+            : undefined;
+        const rowNumbers = (field, source) => field !== undefined && source === FROM_ROW
+            ? stepNumberReader(table, field, 'an aggregate')
+            : undefined;
+        const readValue = rowNumbers(op.field, valueSource);
+        const readWeight = rowNumbers(op.weight, weightSource);
+        if ((valueSource === undefined || readValue) &&
+            (weightSource === undefined ||
+                readWeight ||
+                weightSource === FROM_OVERLAP)) {
+            addByRow(walk, sums, readValue, readWeight, weightSource === FROM_OVERLAP);
+        }
+        else {
+            addByPiece(walk, sums, valueSource, weightSource, readValue, readWeight);
+        }
+        return sums.column(groups);
+    });
+    // A field's value on each group's first piece.
+    const each = (field) => {
+        const source = pieceSource(field, as);
+        const read = readerOf(table.column(field));
+        const out = new Array(groups);
+        for (let g = 0; g < groups; g++) {
+            const i = groupRow[g];
+            const lo = groupBin[g] * size;
+            const hi = lo + size;
+            out[g] =
+                source === FROM_ROW
+                    ? read(i)
+                    : pick(source, 0, lo, hi, Math.min(iv.end[i], hi) - Math.max(iv.start[i], lo));
+        }
+        return out;
+    };
+    return madeGroups({
+        groups,
+        keys: (agg.groupby ?? []).map((field) => [
+            field,
+            each(field).map(groupKey),
+        ]),
+        ops,
+        step: agg,
+        refNames: each('refName'),
+        start: start.slice(0, groups),
+        end: end.slice(0, groups),
+        sectionOf: groupSection,
+        sections: bounds.length,
+    });
+}
+/**
+ * Each bin's group, numbered in the order the pieces meet them, with the
+ * first piece's row, the bin and the section, and each group's extent: its
+ * bin's, or the least start and greatest end its pieces read where `extent`
+ * says where they read them. Answers how many groups there are.
+ */
+function numberGroups({ iv, bounds, size, lowBin, offset, groupOfBin }, out, extent) {
+    const { groupRow, groupBin, groupSection, start, end } = out;
+    let groups = 0;
+    for (let s = 0; s + 1 < bounds.length; s++) {
+        const base = offset[s] - lowBin[s];
+        for (let i = bounds[s]; i < bounds[s + 1]; i++) {
+            const first = iv.first[i];
+            if (Number.isNaN(first)) {
+                continue;
+            }
+            const last = iv.last[i];
+            for (let b = first; b <= last; b++) {
+                let g = groupOfBin[base + b];
+                if (g < 0) {
+                    g = groups++;
+                    groupOfBin[base + b] = g;
+                    groupRow[g] = i;
+                    groupBin[g] = b;
+                    groupSection[g] = s;
+                    start[g] = b * size;
+                    end[g] = b * size + size;
+                }
+            }
+        }
+    }
+    if (extent) {
+        start.fill(Infinity);
+        end.fill(-Infinity);
+        const { startSource, endSource, readRowStart, readRowEnd } = extent;
+        for (let s = 0; s + 1 < bounds.length; s++) {
+            const base = offset[s] - lowBin[s];
+            for (let i = bounds[s]; i < bounds[s + 1]; i++) {
+                const first = iv.first[i];
+                if (Number.isNaN(first)) {
+                    continue;
+                }
+                const ownStart = readRowStart(i);
+                const ownEnd = readRowEnd(i);
+                for (let b = first; b <= iv.last[i]; b++) {
+                    const g = groupOfBin[base + b];
+                    const lo = b * size;
+                    const hi = lo + size;
+                    const overlap = Math.min(iv.end[i], hi) - Math.max(iv.start[i], lo);
+                    start[g] = Math.min(start[g], pick(startSource, ownStart, lo, hi, overlap));
+                    end[g] = Math.max(end[g], pick(endSource, ownEnd, lo, hi, overlap));
+                }
+            }
+        }
+    }
+    return groups;
+}
+/**
+ * One op's sums where its value is its row's and its weight its row's, its
+ * piece's overlap or none: a row whose value or weight is not a number adds
+ * nothing to any bin, so it is skipped whole. A piece's overlap is always a
+ * number, since the row's ends are.
+ */
+function addByRow({ iv, bounds, size, lowBin, offset, groupOfBin }, { sum, weight, min, max, op }, readValue, readWeight, byOverlap) {
+    const readsValue = op !== 'count';
+    for (let s = 0; s + 1 < bounds.length; s++) {
+        const base = offset[s] - lowBin[s];
+        for (let i = bounds[s]; i < bounds[s + 1]; i++) {
+            const first = iv.first[i];
+            const v = readValue ? readValue(i) : Number.NaN;
+            const rowWeight = readWeight ? readWeight(i) : 1;
+            if (Number.isNaN(first) ||
+                (readsValue && !Number.isFinite(v)) ||
+                !Number.isFinite(rowWeight)) {
+                continue;
+            }
+            const rowS = iv.start[i];
+            const rowE = iv.end[i];
+            const last = iv.last[i];
+            for (let b = first; b <= last; b++) {
+                const g = groupOfBin[base + b];
+                const lo = b * size;
+                const w = byOverlap
+                    ? Math.min(rowE, lo + size) - Math.max(rowS, lo)
+                    : rowWeight;
+                weight[g] += w;
+                if (readsValue) {
+                    sum[g] += v * w;
+                    if (v < min[g]) {
+                        min[g] = v;
+                    }
+                    if (v > max[g]) {
+                        max[g] = v;
+                    }
+                }
+            }
+        }
+    }
+}
+/** One op's sums where its value or weight is a field the bin wrote. */
+function addByPiece({ iv, bounds, size, lowBin, offset, groupOfBin }, sums, valueSource, weightSource, readValue, readWeight) {
+    for (let s = 0; s + 1 < bounds.length; s++) {
+        const base = offset[s] - lowBin[s];
+        for (let i = bounds[s]; i < bounds[s + 1]; i++) {
+            const first = iv.first[i];
+            if (Number.isNaN(first)) {
+                continue;
+            }
+            const rowV = readValue ? readValue(i) : Number.NaN;
+            const rowW = readWeight ? readWeight(i) : 1;
+            const last = iv.last[i];
+            for (let b = first; b <= last; b++) {
+                const lo = b * size;
+                const hi = lo + size;
+                const overlap = Math.min(iv.end[i], hi) - Math.max(iv.start[i], lo);
+                sums.add(groupOfBin[base + b], valueSource === undefined
+                    ? Number.NaN
+                    : pick(valueSource, rowV, lo, hi, overlap), weightSource === undefined
+                    ? 1
+                    : pick(weightSource, rowW, lo, hi, overlap));
+            }
+        }
+    }
+}

package/esm/util/cacheBudgets.d.ts

@@ -1,10 +1,10 @@
 import { SharedBudget } from '@gmod/shared-read-cache';
 /**
- * Ceilings on what the indexed-format libraries retain, shared by every adapter
- * in this JS context — so one per RPC worker, plus one on the main thread,
- * which is the scope that actually runs out of memory.
+ * The ceiling on what the indexed-format libraries retain, shared by every
+ * adapter in this JS context — so one per RPC worker, plus one on the main
+ * thread, which is the scope that actually runs out of memory.
  *
- * ## Why these are not per file
+ * ## Why this is not per file
  *
  * `@gmod/bam`, `@gmod/tabix` and `@gmod/cram` each take a per-file budget,
  * sized so that a single track panning never falls off the cliff where a cache
@@ -29,24 +29,27 @@ import { SharedBudget } from '@gmod/shared-read-cache';
  * at hand their space to the one being panned, so the active track keeps a
  * whole working set however many are open.
  *
- * ## The numbers are not new
+ * ## The number is not new
  *
- * Both are the libraries' own per-file defaults, moved from per-file to
- * per-context. That makes this a strict tightening — retention can only fall —
- * and avoids inventing a number that would need its own justification. The
- * budget still has to clear one query's working set or the cliff returns, and
- * on that workload 512 MB shared across three tracks already cost 43 refills
- * where 1 GB cost 4.
+ * 1 GB is the libraries' own per-file default (`DEFAULT_MAX_CACHE_BYTES` in
+ * both `@gmod/bam` and `@gmod/cram`), moved from per-file to per-context. That
+ * makes this a strict tightening — retention can only fall — and avoids
+ * inventing a number that would need its own justification. With one file open
+ * the two ceilings coincide; from the second file on, this one is the one that
+ * binds. The budget still has to clear one query's working set or the cliff
+ * returns, and on that workload 512 MB shared across three tracks already cost
+ * 43 refills where 1 GB cost 4.
  *
- * ## Two budgets, because units cannot mix
+ * ## One budget, because every member weighs bytes
  *
  * `SharedBudget.total` is a sum over its members, so they must all weigh in the
- * same unit. `@gmod/bam` and `@gmod/tabix` weigh decompressed bytes;
- * `@gmod/cram` weighs decoded records, because a decoded record has no cheap
- * size. A single budget spanning them would add records to bytes and bound
- * neither. `sizeOf` is opaque, so nothing can catch that at runtime — hence two
- * budgets named for their units.
+ * same unit, and `sizeOf` is opaque, so nothing could catch a mismatch at
+ * runtime. `@gmod/bam` and `@gmod/tabix` weigh decompressed bytes, and since 14
+ * `@gmod/cram` weighs a decoded slice by `DecodedSlice.byteLength` — its typed
+ * columns exactly and its strings by estimate, within 1–8% of the measured heap
+ * (its ADR 0013). Before that a CRAM slice weighed its record count, which is
+ * why this used to be two budgets named for their units: a million records
+ * could not be added to bytes, and never bound long-read data either, where a
+ * 6 MB slice counted as 37.
  */
 export declare const decompressedBytesBudget: SharedBudget;
-/** See {@link decompressedBytesBudget}. Records, not bytes — CRAM only. */
-export declare const decodedRecordsBudget: SharedBudget;

package/esm/util/cacheBudgets.js

@@ -1,10 +1,10 @@
 import { SharedBudget } from '@gmod/shared-read-cache';
 /**
- * Ceilings on what the indexed-format libraries retain, shared by every adapter
- * in this JS context — so one per RPC worker, plus one on the main thread,
- * which is the scope that actually runs out of memory.
+ * The ceiling on what the indexed-format libraries retain, shared by every
+ * adapter in this JS context — so one per RPC worker, plus one on the main
+ * thread, which is the scope that actually runs out of memory.
  *
- * ## Why these are not per file
+ * ## Why this is not per file
  *
  * `@gmod/bam`, `@gmod/tabix` and `@gmod/cram` each take a per-file budget,
  * sized so that a single track panning never falls off the cliff where a cache
@@ -29,24 +29,27 @@ import { SharedBudget } from '@gmod/shared-read-cache';
  * at hand their space to the one being panned, so the active track keeps a
  * whole working set however many are open.
  *
- * ## The numbers are not new
+ * ## The number is not new
  *
- * Both are the libraries' own per-file defaults, moved from per-file to
- * per-context. That makes this a strict tightening — retention can only fall —
- * and avoids inventing a number that would need its own justification. The
- * budget still has to clear one query's working set or the cliff returns, and
- * on that workload 512 MB shared across three tracks already cost 43 refills
- * where 1 GB cost 4.
+ * 1 GB is the libraries' own per-file default (`DEFAULT_MAX_CACHE_BYTES` in
+ * both `@gmod/bam` and `@gmod/cram`), moved from per-file to per-context. That
+ * makes this a strict tightening — retention can only fall — and avoids
+ * inventing a number that would need its own justification. With one file open
+ * the two ceilings coincide; from the second file on, this one is the one that
+ * binds. The budget still has to clear one query's working set or the cliff
+ * returns, and on that workload 512 MB shared across three tracks already cost
+ * 43 refills where 1 GB cost 4.
  *
- * ## Two budgets, because units cannot mix
+ * ## One budget, because every member weighs bytes
  *
  * `SharedBudget.total` is a sum over its members, so they must all weigh in the
- * same unit. `@gmod/bam` and `@gmod/tabix` weigh decompressed bytes;
- * `@gmod/cram` weighs decoded records, because a decoded record has no cheap
- * size. A single budget spanning them would add records to bytes and bound
- * neither. `sizeOf` is opaque, so nothing can catch that at runtime — hence two
- * budgets named for their units.
+ * same unit, and `sizeOf` is opaque, so nothing could catch a mismatch at
+ * runtime. `@gmod/bam` and `@gmod/tabix` weigh decompressed bytes, and since 14
+ * `@gmod/cram` weighs a decoded slice by `DecodedSlice.byteLength` — its typed
+ * columns exactly and its strings by estimate, within 1–8% of the measured heap
+ * (its ADR 0013). Before that a CRAM slice weighed its record count, which is
+ * why this used to be two budgets named for their units: a million records
+ * could not be added to bytes, and never bound long-read data either, where a
+ * 6 MB slice counted as 37.
  */
 export const decompressedBytesBudget = new SharedBudget(1024 * 2 ** 20);
-/** See {@link decompressedBytesBudget}. Records, not bytes — CRAM only. */
-export const decodedRecordsBudget = new SharedBudget(1_000_000);

package/esm/util/cachedSetup.d.ts

@@ -17,7 +17,7 @@ type OnProgress = (current: number, total?: number) => void;
  *   moment that fetch was superseded — the display's latest-wins guard gates the
  *   old callback off — so the fetch replacing it awaited a multi-GB parse behind
  *   a blank loading overlay.
- * - **`stopToken` is withheld from the shared work.** Honoring one caller's
+ * - **`signal` is withheld from the shared work.** Honoring one caller's
  *   cancel would abort a parse the caller replacing it is already waiting on,
  *   and reject them both. A superseded fetch just stops listening. Cancellation
  *   stays with the per-call work (indexed range queries), which no one else is

package/esm/util/cachedSetup.js

@@ -15,7 +15,7 @@ import { downloadStatus } from './progress.js';
  *   moment that fetch was superseded — the display's latest-wins guard gates the
  *   old callback off — so the fetch replacing it awaited a multi-GB parse behind
  *   a blank loading overlay.
- * - **`stopToken` is withheld from the shared work.** Honoring one caller's
+ * - **`signal` is withheld from the shared work.** Honoring one caller's
  *   cancel would abort a parse the caller replacing it is already waiting on,
  *   and reject them both. A superseded fetch just stops listening. Cancellation
  *   stays with the per-call work (indexed range queries), which no one else is
@@ -39,7 +39,7 @@ export function cachedSetup({ setup, label, }) {
     const run = (opts, onProgress) => {
         cached ??= setup({
             ...opts,
-            stopToken: undefined,
+            signal: undefined,
             statusCallback: status => {
                 for (const cb of waiting) {
                     cb(status);

package/esm/util/categoricalField.d.ts

@@ -0,0 +1,56 @@
+/** #api */
+export declare const STRAND_FIELD = "strand";
+/**
+ * #api
+ * The structural-variant class `svClassOf` names. A VCF record and a BEDPE
+ * row carry it, and the mark display's `mate` step writes it per allele.
+ */
+export declare const SV_TYPE_FIELD = "svType";
+/**
+ * #api
+ * The row a feature with nothing in a categorical field lands on, so a key
+ * says why a mark is grey rather than listing a blank value.
+ */
+export declare const NO_VALUE_LABEL = "(no value)";
+/**
+ * #api
+ * One categorical field as every channel reads it — a facet's sections, a
+ * color's range entries, a key's rows. `key` files a value, `compare`
+ * orders keys (the `domain` first, the rest by `compareGroupKeys`, `''`
+ * after them), `label` names a key in a legend, `sectionLabel` on a chip, and
+ * `color` paints it. A key's color depends only on the key and the
+ * declaration, so every region agrees on it.
+ */
+export interface CategoricalField {
+    field: string;
+    /** The declared order, or the field's own where none is declared. */
+    domain: readonly string[];
+    /**
+     * Every key a value can file under is in `domain`, as a threshold scale's
+     * bins are, so a key lists all of them whether or not anything painted one.
+     */
+    closed?: boolean;
+    key: (value: unknown) => string;
+    compare: (a: string, b: string) => number;
+    label: (key: string) => string;
+    sectionLabel: (key: string) => string;
+    color: (key: string) => string;
+}
+/**
+ * #api
+ * What a key names each of `keys`, from a colour object's `labels`: one each in
+ * order, an empty or missing entry leaving that key its own name. Every key
+ * that takes `labels` reads them through this, so a config means one thing by
+ * them everywhere.
+ */
+export declare function keyNames(keys: readonly unknown[], labels?: readonly string[]): ReadonlyMap<string, string>;
+/**
+ * #api
+ * `labels` names the `domain`'s values in a key, one each in order, where a
+ * config spells them for a reader rather than as the data does.
+ */
+export declare function categoricalField(field: string, { domain, range, labels, }?: {
+    domain?: readonly string[];
+    range?: readonly string[];
+    labels?: readonly string[];
+}): CategoricalField;

package/esm/util/categoricalField.js

@@ -0,0 +1,73 @@
+import { categoricalColorScale } from '../ui/colors.js';
+import { NO_CATEGORY_COLOR } from './color/index.js';
+import { universalPresetOf } from './colorScale.js';
+import { groupKeyComparator, valueText } from './groupKeys.js';
+/** #api */
+export const STRAND_FIELD = 'strand';
+/**
+ * #api
+ * The structural-variant class `svClassOf` names. A VCF record and a BEDPE
+ * row carry it, and the mark display's `mate` step writes it per allele.
+ */
+export const SV_TYPE_FIELD = 'svType';
+/**
+ * #api
+ * The row a feature with nothing in a categorical field lands on, so a key
+ * says why a mark is grey rather than listing a blank value.
+ */
+export const NO_VALUE_LABEL = '(no value)';
+/**
+ * #api
+ * What a key names each of `keys`, from a colour object's `labels`: one each in
+ * order, an empty or missing entry leaving that key its own name. Every key
+ * that takes `labels` reads them through this, so a config means one thing by
+ * them everywhere.
+ */
+export function keyNames(keys, labels = []) {
+    const names = new Map();
+    keys.forEach((key, i) => {
+        const name = labels[i];
+        const text = String(key);
+        if (name && !names.has(text)) {
+            names.set(text, name);
+        }
+    });
+    return names;
+}
+/**
+ * #api
+ * `labels` names the `domain`'s values in a key, one each in order, where a
+ * config spells them for a reader rather than as the data does.
+ */
+export function categoricalField(field, { domain = [], range = [], labels = [], } = {}) {
+    // a field with a vocabulary of its own reads it on every channel, a facet's
+    // sections as well as a colour's key
+    const vocabulary = universalPresetOf(field);
+    const ownOrder = vocabulary?.domain ?? [];
+    const order = domain.length > 0 ? domain : ownOrder;
+    const [paired, colors] = range.length > 0 || !vocabulary
+        ? [order, range]
+        : [ownOrder, vocabulary.range ?? []];
+    const declared = keyNames(order, labels);
+    const own = vocabulary && keyNames(ownOrder, vocabulary.labels);
+    const named = (key) => declared.get(key) ?? own?.get(key);
+    let colorOf;
+    return {
+        field,
+        domain: order,
+        key: value => {
+            const key = valueText(value);
+            return key === '' ? (vocabulary?.missing ?? key) : key;
+        },
+        compare: groupKeyComparator(order),
+        label: key => named(key) ?? (key === '' ? NO_VALUE_LABEL : key),
+        sectionLabel: key => named(key) ?? `${field}: ${key === '' ? 'none' : key}`,
+        color: key => {
+            if (key === '') {
+                return NO_CATEGORY_COLOR;
+            }
+            colorOf ??= categoricalColorScale(paired, colors);
+            return colorOf(key);
+        },
+    };
+}

package/esm/util/clampToContig.d.ts

@@ -24,3 +24,20 @@ export declare function clampToContig(assembly: Assembly, region: {
     start: number;
     end: number;
 }): Region | undefined;
+/**
+ * `clampToContig` for a refName that may not be on the assembly at all, which
+ * is the shape a location nobody requested arrives in — a BAM's `nextRef`, an
+ * SA record's contig (REFNAME_NAMESPACES.md). `clampToContig` alone passes an
+ * unknown name through with nothing to clamp against, so it cannot tell "past
+ * the end of a contig we have" from "a contig we do not have", and both callers
+ * need that apart to say which happened.
+ */
+export declare function clampToListedContig(assembly: Assembly, region: {
+    refName: string;
+    start: number;
+    end: number;
+}): {
+    refName: string;
+    onAssembly: boolean;
+    region: Region | undefined;
+};

package/esm/util/clampToContig.js

@@ -26,3 +26,22 @@ export function clampToContig(assembly, region) {
         ? { ...region, assemblyName: assembly.name, refName, start, end }
         : undefined;
 }
+/**
+ * `clampToContig` for a refName that may not be on the assembly at all, which
+ * is the shape a location nobody requested arrives in — a BAM's `nextRef`, an
+ * SA record's contig (REFNAME_NAMESPACES.md). `clampToContig` alone passes an
+ * unknown name through with nothing to clamp against, so it cannot tell "past
+ * the end of a contig we have" from "a contig we do not have", and both callers
+ * need that apart to say which happened.
+ */
+export function clampToListedContig(assembly, region) {
+    const refName = assembly.getCanonicalRefName2(region.refName);
+    const onAssembly = assembly.getRegionForRefName(refName) !== undefined;
+    return {
+        refName,
+        onAssembly,
+        region: onAssembly
+            ? clampToContig(assembly, { ...region, refName })
+            : undefined,
+    };
+}

package/esm/util/coarseStripHTML.js

@@ -1,5 +1,4 @@
-// not a sanitizer, this just removes html tags for use in measureText-based
-// element width calculations
+// not a sanitizer, this just removes html tags where only the text is shown
 export function coarseStripHTML(s) {
     return s.replaceAll(/<[^<>]*>/g, '');
 }

package/esm/util/color/cssColorsLevel4.d.ts

@@ -1,2 +1,3 @@
 export declare function namedColorToHex(name: string): string | undefined;
 export declare function isNamedColor(name: string): boolean;
+export declare const CSS_COLOR_NAMES: readonly string[];

package/esm/util/color/cssColorsLevel4.js

@@ -158,3 +158,4 @@ export function namedColorToHex(name) {
 export function isNamedColor(name) {
     return Object.hasOwn(colors, name);
 }
+export const CSS_COLOR_NAMES = Object.keys(colors);

package/esm/util/color/index.d.ts

@@ -20,7 +20,9 @@ export declare function emphasize(color: string, coefficient?: number): string;
  * default refName colors.
  */
 export declare function makeContrasting(foreground: string, background?: string, minContrastRatio?: number): string;
-export { isNamedColor, namedColorToHex } from './cssColorsLevel4.ts';
+export { CSS_COLOR_NAMES, isNamedColor, namedColorToHex, } from './cssColorsLevel4.ts';
+export declare const NO_CATEGORY_COLOR = "#afafaf";
+export declare const MISCONFIGURED_COLOR = "#808080";
 /**
  * #api
  * Move a color's OKLCH lightness by `lightnessShift` and scale its chroma,
@@ -69,8 +71,8 @@ export declare function relight(color: string, lightnessShift: number, chromaSca
  *
  * A value that is absent gets NO_CATEGORY_COLOR rather than a hue, and that is
  * the difference between this being usable on real data and not. The everyday
- * caller is the Color-by-attribute dialog, which writes
- * `jexl:randomColor(get(feature,'<attr>'))` over a whole track — and most files
+ * caller is a `jexl:randomColor(get(feature,'<attr>'))` color slot over a
+ * whole track — and most files
  * have the attribute on some features and not others, so most of the time this
  * is handed `undefined`. It used to throw on that (`str.length` of undefined),
  * once per feature, and what a reader saw was every unlabelled feature in one