@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/util/calculateStaticBlocks.js

@@ -1,103 +1,80 @@
-import { getSnapshot, isStateTreeNode } from '@jbrowse/mobx-state-tree';
-import { BlockSet, ContentBlock, ElidedBlock, InterRegionPaddingBlock, } from "./blockTypes.js";
-import { assembleLocStringFast } from "./index.js";
-export default function calculateStaticBlocks(model, padding = true, elision = true, extra = 0, width = 800) {
-    const { offsetPx, displayedRegions, bpPerPx, minimumBlockWidth, interRegionPaddingWidth, width: modelWidth, } = model;
+import { BlockSet } from './blockTypes.js';
+const blockSizeCssPx = 800;
+export default function calculateStaticBlocks(model, padding = true, elision = true) {
+    const { offsetPx, displayedRegions, bpPerPx, minimumBlockWidth, width: modelWidth, } = model;
     const windowLeftBp = offsetPx * bpPerPx;
     const windowRightBp = (offsetPx + modelWidth) * bpPerPx;
-    const blockSizePx = width;
-    const blockSizeBp = Math.ceil(blockSizePx * bpPerPx);
+    const blockSizeBp = Math.ceil(blockSizeCssPx * bpPerPx);
     const invBpPerPx = 1 / bpPerPx;
     const invBlockSizeBp = 1 / blockSizeBp;
     let regionBpOffset = 0;
     const blocks = new BlockSet();
-    for (let regionNumber = 0; regionNumber < displayedRegions.length; regionNumber++) {
-        const region = displayedRegions[regionNumber];
-        const { assemblyName, refName, start: regionStart, end: regionEnd, reversed, } = region;
-        const regionBlockCount = Math.ceil((regionEnd - regionStart) * invBlockSizeBp);
-        const parentRegion = isStateTreeNode(region) ? getSnapshot(region) : region;
-        let windowRightBlockNum = Math.floor((windowRightBp - regionBpOffset) * invBlockSizeBp) + extra;
-        if (windowRightBlockNum >= regionBlockCount) {
-            windowRightBlockNum = regionBlockCount - 1;
-        }
-        let windowLeftBlockNum = Math.floor((windowLeftBp - regionBpOffset) * invBlockSizeBp) - extra;
-        if (windowLeftBlockNum < 0) {
-            windowLeftBlockNum = 0;
+    for (let displayedRegionIndex = 0; displayedRegionIndex < displayedRegions.length; displayedRegionIndex++) {
+        // Regions are laid out left to right, so once the cursor passes the window's
+        // right edge nothing further can contribute a block — and the trailing
+        // padding block needs the last region to be in view anyway. A whole-genome
+        // view holds one region per refName, so without this the loop (and its five
+        // MST observable reads per region) runs thousands of times per zoom frame to
+        // emit a handful of blocks.
+        if (regionBpOffset > windowRightBp) {
+            break;
         }
+        const { assemblyName, refName, start: regionStart, end: regionEnd, reversed, } = displayedRegions[displayedRegionIndex];
+        const regionBlockCount = Math.ceil((regionEnd - regionStart) * invBlockSizeBp);
+        const windowRightBlockNum = Math.min(Math.floor((windowRightBp - regionBpOffset) * invBlockSizeBp), regionBlockCount - 1);
+        const windowLeftBlockNum = Math.max(Math.floor((windowLeftBp - regionBpOffset) * invBlockSizeBp), 0);
         const regionWidthPx = (regionEnd - regionStart) * invBpPerPx;
-        for (let blockNum = windowLeftBlockNum; blockNum <= windowRightBlockNum; blockNum += 1) {
+        for (let blockNum = windowLeftBlockNum; blockNum <= windowRightBlockNum; blockNum++) {
+            const isLeftEndOfDisplayedRegion = blockNum === 0;
+            const isRightEndOfDisplayedRegion = blockNum === regionBlockCount - 1;
             let start;
             let end;
-            let isLeftEndOfDisplayedRegion;
-            let isRightEndOfDisplayedRegion;
             if (reversed) {
                 start = Math.max(regionStart, regionEnd - (blockNum + 1) * blockSizeBp);
                 end = regionEnd - blockNum * blockSizeBp;
-                isLeftEndOfDisplayedRegion = end === regionEnd;
-                isRightEndOfDisplayedRegion = start === regionStart;
             }
             else {
                 start = regionStart + blockNum * blockSizeBp;
                 end = Math.min(regionEnd, regionStart + (blockNum + 1) * blockSizeBp);
-                isLeftEndOfDisplayedRegion = start === regionStart;
-                isRightEndOfDisplayedRegion = end === regionEnd;
             }
             const widthPx = (end - start) * invBpPerPx;
-            const blockData = {
+            const blockOffsetPx = (regionBpOffset + blockNum * blockSizeBp) * invBpPerPx;
+            const key = `${assemblyName}:${refName}:${start}:${end}:${displayedRegionIndex}${reversed ? ':rev' : ''}`;
+            if (padding && displayedRegionIndex === 0 && blockNum === 0) {
+                blocks.push({
+                    type: 'InterRegionPaddingBlock',
+                    key: `${key}-beforeFirstRegion`,
+                    widthPx: blockSizeCssPx,
+                    offsetPx: blockOffsetPx - blockSizeCssPx,
+                    variant: 'boundary',
+                });
+            }
+            const data = {
                 assemblyName,
                 refName,
                 start,
                 end,
                 reversed,
-                offsetPx: (regionBpOffset + blockNum * blockSizeBp) * invBpPerPx,
-                parentRegion,
-                regionNumber,
+                offsetPx: blockOffsetPx,
+                displayedRegionIndex,
                 widthPx,
                 isLeftEndOfDisplayedRegion,
                 isRightEndOfDisplayedRegion,
-                key: `${assembleLocStringFast({
-                    assemblyName,
-                    refName,
-                    start,
-                    end,
-                    reversed,
-                })}-${regionNumber}${reversed ? '-reversed' : ''}`,
+                key,
             };
-            if (padding && regionNumber === 0 && blockNum === 0) {
-                blocks.push(new InterRegionPaddingBlock({
-                    key: `${blockData.key}-beforeFirstRegion`,
-                    widthPx: width,
-                    offsetPx: blockData.offsetPx - width,
+            blocks.push(elision && regionWidthPx < minimumBlockWidth
+                ? { ...data, type: 'ElidedBlock' }
+                : { ...data, type: 'ContentBlock' });
+            if (padding &&
+                displayedRegionIndex === displayedRegions.length - 1 &&
+                isRightEndOfDisplayedRegion) {
+                blocks.push({
+                    type: 'InterRegionPaddingBlock',
+                    key: `${key}-afterLastRegion`,
+                    widthPx: blockSizeCssPx,
+                    offsetPx: blockOffsetPx + widthPx,
                     variant: 'boundary',
-                }));
-            }
-            if (elision && regionWidthPx < minimumBlockWidth) {
-                blocks.push(new ElidedBlock(blockData));
-            }
-            else {
-                blocks.push(new ContentBlock(blockData));
-            }
-            if (padding) {
-                if (regionWidthPx >= minimumBlockWidth &&
-                    blockData.isRightEndOfDisplayedRegion &&
-                    regionNumber < displayedRegions.length - 1) {
-                    regionBpOffset += interRegionPaddingWidth * bpPerPx;
-                    blocks.push(new InterRegionPaddingBlock({
-                        key: `${blockData.key}-rightpad`,
-                        widthPx: interRegionPaddingWidth,
-                        offsetPx: blockData.offsetPx + blockData.widthPx,
-                    }));
-                }
-                if (regionNumber === displayedRegions.length - 1 &&
-                    blockData.isRightEndOfDisplayedRegion) {
-                    regionBpOffset += interRegionPaddingWidth * bpPerPx;
-                    blocks.push(new InterRegionPaddingBlock({
-                        key: `${blockData.key}-afterLastRegion`,
-                        widthPx: width,
-                        offsetPx: blockData.offsetPx + blockData.widthPx,
-                        variant: 'boundary',
-                    }));
-                }
+                });
             }
         }
         regionBpOffset += regionEnd - regionStart;

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/chooseGridPitch.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Given a scale ( bp/px ) and minimum distances (px) between major and minor
+ * gridlines, return an object like `{ majorPitch: bp, minorPitch: bp }` giving
+ * the gridline pitches to use.
+ */
+export declare function chooseGridPitch(scale: number, minMajorPitchPx: number, minMinorPitchPx: number): {
+    majorPitch: number;
+    minorPitch: number;
+};

package/esm/util/chooseGridPitch.js

@@ -0,0 +1,31 @@
+/**
+ * Given a scale ( bp/px ) and minimum distances (px) between major and minor
+ * gridlines, return an object like `{ majorPitch: bp, minorPitch: bp }` giving
+ * the gridline pitches to use.
+ */
+export function chooseGridPitch(scale, minMajorPitchPx, minMinorPitchPx) {
+    scale = Math.abs(scale);
+    const minMajorPitchBp = minMajorPitchPx * scale;
+    const majorMagnitude = +minMajorPitchBp.toExponential().split(/e/i, 2)[1];
+    let majorPitch = 10 ** majorMagnitude;
+    while (majorPitch < minMajorPitchBp) {
+        majorPitch *= 2;
+        if (majorPitch >= minMajorPitchBp) {
+            break;
+        }
+        majorPitch *= 2.5;
+    }
+    majorPitch = Math.max(majorPitch, 5);
+    const majorPitchPx = majorPitch / scale;
+    let minorPitch = 0;
+    if (!(majorPitch % 10) && majorPitchPx / 10 >= minMinorPitchPx) {
+        minorPitch = majorPitch / 10;
+    }
+    else if (!(majorPitch % 5) && majorPitchPx / 5 >= minMinorPitchPx) {
+        minorPitch = majorPitch / 5;
+    }
+    else if (!(majorPitch % 2) && majorPitchPx / 2 >= minMinorPitchPx) {
+        minorPitch = majorPitch / 2;
+    }
+    return { majorPitch, minorPitch };
+}

package/esm/util/clampToContig.d.ts

@@ -0,0 +1,43 @@
+import type { Assembly } from '../assemblyManager/assembly.ts';
+import type { Region } from './types/data.ts';
+/**
+ * Clamp a span to the extents of the contig it names, resolving the refName to
+ * canonical on the way. Returns undefined when the clamp leaves nothing — the
+ * span lies wholly off the end of the contig.
+ *
+ * **The undefined is the point.** A one-sided clamp is the shape this keeps
+ * getting written as, and it inverts: a span past the contig end comes back with
+ * its end below its start, which every consumer that SUMS region lengths then
+ * subtracts. That is silent, and it happens for real, on a GFF3 or a BAM
+ * annotated against a longer assembly than the FASTA in use — which JBrowse
+ * otherwise just draws past the end of. Two callers wrote the one-sided version
+ * and only one of them ever guarded it.
+ *
+ * `start` is floored at 0 even when the contig extents are unknown (`regions`
+ * still loading, or a refName this assembly doesn't have), because interbase has
+ * no coordinate below 0 whatever the contig turns out to be. Only the high end
+ * needs a length to clamp against, so without one it is left alone — and with no
+ * high bound there is nothing to invert, so such a span always comes back.
+ */
+export declare function clampToContig(assembly: Assembly, region: {
+    refName: string;
+    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

@@ -0,0 +1,47 @@
+/**
+ * Clamp a span to the extents of the contig it names, resolving the refName to
+ * canonical on the way. Returns undefined when the clamp leaves nothing — the
+ * span lies wholly off the end of the contig.
+ *
+ * **The undefined is the point.** A one-sided clamp is the shape this keeps
+ * getting written as, and it inverts: a span past the contig end comes back with
+ * its end below its start, which every consumer that SUMS region lengths then
+ * subtracts. That is silent, and it happens for real, on a GFF3 or a BAM
+ * annotated against a longer assembly than the FASTA in use — which JBrowse
+ * otherwise just draws past the end of. Two callers wrote the one-sided version
+ * and only one of them ever guarded it.
+ *
+ * `start` is floored at 0 even when the contig extents are unknown (`regions`
+ * still loading, or a refName this assembly doesn't have), because interbase has
+ * no coordinate below 0 whatever the contig turns out to be. Only the high end
+ * needs a length to clamp against, so without one it is left alone — and with no
+ * high bound there is nothing to invert, so such a span always comes back.
+ */
+export function clampToContig(assembly, region) {
+    const refName = assembly.getCanonicalRefName2(region.refName);
+    const bounds = assembly.getRegionForRefName(refName);
+    const start = Math.max(bounds?.start ?? 0, region.start);
+    const end = bounds ? Math.min(bounds.end, region.end) : region.end;
+    return end > start
+        ? { ...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/cmpStr.d.ts

@@ -0,0 +1 @@
+export declare function cmpStr(a: string, b: string): number;

package/esm/util/cmpStr.js

@@ -0,0 +1,7 @@
+// Deterministic, locale-independent string ordering. Returns 0 when equal so
+// it chains with `||` in multi-key comparators. Prefer this over
+// `localeCompare` wherever the order must be reproducible across environments
+// (e.g. sort keys feeding deterministic worker output or screenshot renders).
+export function cmpStr(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/esm/util/coarseStripHTML.js

@@ -1,17 +1,4 @@
+// not a sanitizer, this just removes html tags where only the text is shown
 export function coarseStripHTML(s) {
-    let result = '';
-    let inTag = false;
-    for (let i = 0, l = s.length; i < l; i++) {
-        const char = s[i];
-        if (char === '<') {
-            inTag = true;
-        }
-        else if (char === '>') {
-            inTag = false;
-        }
-        else if (!inTag) {
-            result += char;
-        }
-    }
-    return result;
+    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

@@ -1,3 +1,4 @@
+// from https://www.w3.org/TR/css-color-4/#named-colors
 const colors = {
     aliceblue: '#F0F8FF',
     antiquewhite: '#FAEBD7',
@@ -148,9 +149,13 @@ const colors = {
     yellow: '#FFFF00',
     yellowgreen: '#9ACD32',
 };
+// Object.hasOwn rather than a bare index: the table is a plain object, so
+// `colors.constructor` and `colors.toString` come back as functions typed
+// `string`, and isNamedColor('toString') was true.
 export function namedColorToHex(name) {
-    return colors[name];
+    return Object.hasOwn(colors, name) ? colors[name] : undefined;
 }
 export function isNamedColor(name) {
-    return !!colors[name];
+    return Object.hasOwn(colors, name);
 }
+export const CSS_COLOR_NAMES = Object.keys(colors);

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

@@ -1,5 +1,86 @@
-export declare function contrastingTextColor(color: string): string;
+/**
+ * Darken or lighten a color, depending on its luminance.
+ * Light colors are darkened, dark colors are lightened.
+ *
+ * @param color - CSS color, i.e. one of: #nnn, #nnnnnn, rgb(), rgba(),
+ * hsl(), hsla(), or named color
+ * @param coefficient - multiplier in the range 0 - 1, defaults to 0.15
+ * @returns A CSS color string. Hex input values are returned as rgb
+ */
 export declare function emphasize(color: string, coefficient?: number): string;
+/**
+ * Push `foreground` away from `background` until it clears `minContrastRatio`,
+ * returning the closest it got when that ratio is unreachable.
+ *
+ * `minContrastRatio` genuinely cannot be met against a mid-luminance
+ * background: lighten/darken clamp their coefficient at 1, so the candidate
+ * pins at white/black, and against a `#b0b0b0` paper the best ratio any color
+ * reaches is about 2.2. This used to be a `while (ratio < min)` loop with an
+ * unbounded coefficient, which froze the render thread outright for 38 of the 40
+ * default refName colors.
+ */
 export declare function makeContrasting(foreground: string, background?: string, minContrastRatio?: number): string;
-export { isNamedColor, namedColorToHex } from './cssColorsLevel4.ts';
-export declare function randomColor(str: string): string;
+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,
+ * holding its hue.
+ *
+ * For extending a categorical palette past its length. Cycling a nine-color
+ * list over a 24-chromosome karyotype repeats the color outright; cycling it
+ * with a lightness shift per lap gives the hue back as a variant still told
+ * apart from the original — tab20's construction, which pairs a light and a
+ * dark of each hue.
+ *
+ * SHIFT rather than a fixed lightness, and SCALE rather than a fixed chroma,
+ * because a categorical palette is uneven on purpose: category10's brown and
+ * its red are 5 degrees apart in hue and are told apart by chroma alone, so
+ * re-lighting both to one (lightness, chroma) makes them the same color.
+ * Keeping each color's own relative chroma keeps brown reading as brown.
+ *
+ * In OKLCH rather than through `lighten`/`darken`, which work in sRGB, where
+ * the same coefficient moves a yellow and a blue by visibly different amounts:
+ * a lap has to read as one tone across the whole palette or it reads as noise.
+ *
+ * @param color - CSS color to transform
+ * @param lightnessShift - added to its OKLCH lightness (which is 0 - 1)
+ * @param chromaScale - multiplies its OKLCH chroma; the result is reduced at
+ *  constant hue if that lands out of gamut
+ * @returns A CSS hex color string
+ */
+export declare function relight(color: string, lightnessShift: number, chromaScale?: number): string;
+/**
+ * Generate a consistent random color for a given string.
+ * The same string will always generate the same color, with no shared palette
+ * state — so the same value (e.g. a gene symbol used as an ortholog id) gets the
+ * same color across independent tracks/panels.
+ *
+ * Statelessness is why this hashes into a color space rather than indexing a
+ * fixed palette of N: with no allocator there is no "next unused color", so an
+ * N-color palette collides by the birthday problem — six values into a
+ * twenty-color palette collide more often than not — while a hue circle does
+ * not repeat until 360 values. What a curated palette actually buys is
+ * perceptual evenness, and that comes from the space, not the list: hues are
+ * placed in OKLCH at a fixed lightness and chroma, so every value is equally
+ * light and equally colorful. HSL, which this used to use, is neither — its
+ * hue wheel spends a quarter of itself on greens that look identical and a
+ * sliver on yellow, and at one lightness its yellows glare while its blues go
+ * murky. That unevenness is what reads as "random RGB".
+ *
+ * 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 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
+ * strong color: a large fake category, drawn over the real ones. Grey says the
+ * only true thing about a feature with no value for the attribute you asked to
+ * colour by.
+ *
+ * @param str - The string to generate a color from
+ * @returns A CSS hex color string
+ */
+export declare function randomColor(str: string | undefined | null): string;