@jbrowse/core 4.3.0 → 5.0.0-beta.1

package/esm/util/calculateDynamicBlocks.js

@@ -1,104 +1,107 @@
-import { getSnapshot, isStateTreeNode } from '@jbrowse/mobx-state-tree';
-import { BlockSet, ContentBlock, ElidedBlock, InterRegionPaddingBlock, } from "./blockTypes.js";
-import { assembleLocStringFast } from "./index.js";
-import { intersection2 } from "./range.js";
+import { BlockSet } from './blockTypes.js';
+import { intersection2 } from './range.js';
+/**
+ * Returns a BlockSet covering only the regions currently visible in the view.
+ * Used by tracks where static blocks are not feasible. start/end/offsetPx may
+ * be fractional.
+ */
 export default function calculateDynamicBlocks(model, padding = true, elision = true) {
-    const { offsetPx, displayedRegions, bpPerPx, width, minimumBlockWidth, interRegionPaddingWidth, } = model;
-    if (!width) {
-        throw new Error('view has no width, cannot calculate displayed blocks');
-    }
+    const { offsetPx, displayedRegions, bpPerPx, width, minimumBlockWidth } = model;
+    // A zero-width view yields an empty BlockSet: intersection2 rejects the
+    // degenerate window, so the loop pushes nothing. Mirrors calculateStaticBlocks
+    // rather than throwing inside what callers read as a MobX computed.
     const invBpPerPx = 1 / bpPerPx;
     const blocks = new BlockSet();
     let displayedRegionLeftPx = 0;
     const windowLeftPx = offsetPx;
     const windowRightPx = windowLeftPx + width;
-    for (let regionNumber = 0; regionNumber < displayedRegions.length; regionNumber++) {
-        const region = displayedRegions[regionNumber];
-        const { assemblyName, refName, start: regionStart, end: regionEnd, reversed, } = region;
-        const displayedRegionRightPx = displayedRegionLeftPx + (regionEnd - regionStart) * invBpPerPx;
+    const lastRegionIndex = displayedRegions.length - 1;
+    for (let displayedRegionIndex = 0; displayedRegionIndex < displayedRegions.length; displayedRegionIndex++) {
+        // see calculateStaticBlocks: regions are laid out left to right, so nothing
+        // past the window's right edge can intersect it
+        if (displayedRegionLeftPx > windowRightPx) {
+            break;
+        }
+        const region = displayedRegions[displayedRegionIndex];
+        const { start: regionStart, end: regionEnd, reversed } = region;
         const regionWidthPx = (regionEnd - regionStart) * invBpPerPx;
-        const parentRegion = isStateTreeNode(region) ? getSnapshot(region) : region;
+        const displayedRegionRightPx = displayedRegionLeftPx + regionWidthPx;
         const [leftPx, rightPx] = intersection2(windowLeftPx, windowRightPx, displayedRegionLeftPx, displayedRegionRightPx);
         if (leftPx !== undefined && rightPx !== undefined) {
-            let start;
-            let end;
-            let isLeftEndOfDisplayedRegion;
-            let isRightEndOfDisplayedRegion;
-            let blockOffsetPx;
-            if (reversed) {
-                start = Math.max(regionStart, regionEnd - (rightPx - displayedRegionLeftPx) * bpPerPx);
-                end = regionEnd - (leftPx - displayedRegionLeftPx) * bpPerPx;
-                isLeftEndOfDisplayedRegion = end === regionEnd;
-                isRightEndOfDisplayedRegion = start === regionStart;
-                blockOffsetPx = displayedRegionLeftPx + (regionEnd - end) * invBpPerPx;
-            }
-            else {
-                start = (leftPx - displayedRegionLeftPx) * bpPerPx + regionStart;
-                end = Math.min(regionEnd, (rightPx - displayedRegionLeftPx) * bpPerPx + regionStart);
-                isLeftEndOfDisplayedRegion = start === regionStart;
-                isRightEndOfDisplayedRegion = end === regionEnd;
-                blockOffsetPx =
-                    displayedRegionLeftPx + (start - regionStart) * invBpPerPx;
-            }
+            // bp spanned between the region's left edge and the clipped block edges
+            const leftBp = (leftPx - displayedRegionLeftPx) * bpPerPx;
+            const rightBp = (rightPx - displayedRegionLeftPx) * bpPerPx;
+            const start = reversed
+                ? Math.max(regionStart, regionEnd - rightBp)
+                : regionStart + leftBp;
+            const end = reversed
+                ? regionEnd - leftBp
+                : Math.min(regionEnd, regionStart + rightBp);
+            // both reversed/forward offset formulae reduce algebraically to leftPx
+            const blockOffsetPx = leftPx;
             const widthPx = (end - start) * invBpPerPx;
-            const blockData = {
-                assemblyName,
-                refName,
-                start,
-                end,
-                reversed,
-                offsetPx: blockOffsetPx,
-                parentRegion,
-                regionNumber,
-                widthPx,
-                isLeftEndOfDisplayedRegion,
-                isRightEndOfDisplayedRegion,
-                key: `${assembleLocStringFast({
+            // Under minimumBlockWidth this region is elided, and BlockSet merges an
+            // elided block into a preceding elided run keeping only its widthPx — so
+            // building the key and the block object is work thrown away, which at
+            // whole-genome zoom on a fragmented assembly is nearly every region and
+            // most of the frame. Two edges keep the skip output-identical: the first
+            // region can never take it, because nothing has been pushed for the run
+            // to merge into, so its leading padding block still gets built; the last
+            // region is held out, because it may still owe a trailing padding block
+            // keyed off its own key.
+            const merged = elision &&
+                regionWidthPx < minimumBlockWidth &&
+                displayedRegionIndex !== lastRegionIndex &&
+                blocks.growElidedRun(widthPx);
+            if (!merged) {
+                const { assemblyName, refName } = region;
+                // Pixel comparisons avoid the bpPerPx round-trip float drift that can
+                // make end !== regionEnd even when the full region is in view.
+                const isLeftEndOfDisplayedRegion = leftPx <= displayedRegionLeftPx;
+                const isRightEndOfDisplayedRegion = rightPx >= displayedRegionRightPx;
+                const key = `${assemblyName}:${refName}:${start}:${end}:${displayedRegionIndex}${reversed ? ':rev' : ''}`;
+                if (padding &&
+                    displayedRegionIndex === 0 &&
+                    isLeftEndOfDisplayedRegion) {
+                    blocks.push({
+                        type: 'InterRegionPaddingBlock',
+                        key: `${key}-beforeFirstRegion`,
+                        widthPx: -offsetPx,
+                        offsetPx: blockOffsetPx + offsetPx,
+                        variant: 'boundary',
+                    });
+                }
+                const data = {
                     assemblyName,
                     refName,
                     start,
                     end,
                     reversed,
-                })}-${regionNumber}${reversed ? '-reversed' : ''}`,
-            };
-            if (padding && blocks.length === 0 && isLeftEndOfDisplayedRegion) {
-                blocks.push(new InterRegionPaddingBlock({
-                    key: `${blockData.key}-beforeFirstRegion`,
-                    widthPx: -offsetPx,
-                    offsetPx: blockData.offsetPx + offsetPx,
-                    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) {
-                    blocks.push(new InterRegionPaddingBlock({
-                        key: `${blockData.key}-rightpad`,
-                        widthPx: interRegionPaddingWidth,
-                        offsetPx: blockData.offsetPx + blockData.widthPx,
-                    }));
-                    displayedRegionLeftPx += interRegionPaddingWidth;
-                }
-                if (regionNumber === displayedRegions.length - 1 &&
-                    blockData.isRightEndOfDisplayedRegion) {
-                    blockOffsetPx = blockData.offsetPx + blockData.widthPx;
-                    blocks.push(new InterRegionPaddingBlock({
-                        key: `${blockData.key}-afterLastRegion`,
-                        widthPx: width - blockOffsetPx + offsetPx,
-                        offsetPx: blockOffsetPx,
+                    offsetPx: blockOffsetPx,
+                    displayedRegionIndex,
+                    widthPx,
+                    isLeftEndOfDisplayedRegion,
+                    isRightEndOfDisplayedRegion,
+                    key,
+                };
+                blocks.push(elision && regionWidthPx < minimumBlockWidth
+                    ? { ...data, type: 'ElidedBlock' }
+                    : { ...data, type: 'ContentBlock' });
+                if (padding &&
+                    displayedRegionIndex === lastRegionIndex &&
+                    isRightEndOfDisplayedRegion) {
+                    const afterOffsetPx = blockOffsetPx + widthPx;
+                    blocks.push({
+                        type: 'InterRegionPaddingBlock',
+                        key: `${key}-afterLastRegion`,
+                        widthPx: width - afterOffsetPx + offsetPx,
+                        offsetPx: afterOffsetPx,
                         variant: 'boundary',
-                    }));
+                    });
                 }
             }
         }
-        displayedRegionLeftPx += (regionEnd - regionStart) * invBpPerPx;
+        displayedRegionLeftPx += regionWidthPx;
     }
     return blocks;
 }

package/esm/util/calculateStaticBlocks.d.ts

@@ -1,5 +1,5 @@
 import { BlockSet } from './blockTypes.ts';
-import type { Region } from './types/index.ts';
+import type { Region } from './types/data.ts';
 import type { Region as RegionModel } from './types/mst.ts';
 import type { Instance } from '@jbrowse/mobx-state-tree';
 export interface Base1DViewModel {
@@ -8,6 +8,5 @@ export interface Base1DViewModel {
     displayedRegions: (Region | Instance<typeof RegionModel>)[];
     bpPerPx: number;
     minimumBlockWidth: number;
-    interRegionPaddingWidth: number;
 }
-export default function calculateStaticBlocks(model: Base1DViewModel, padding?: boolean, elision?: boolean, extra?: number, width?: number): BlockSet;
+export default function calculateStaticBlocks(model: Base1DViewModel, padding?: boolean, elision?: boolean): BlockSet;

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/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,26 @@
+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;

package/esm/util/clampToContig.js

@@ -0,0 +1,28 @@
+/**
+ * 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;
+}

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,5 @@
+// not a sanitizer, this just removes html tags for use in measureText-based
+// element width calculations
 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.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,12 @@ 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);
 }

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

@@ -1,5 +1,84 @@
-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;
+/**
+ * #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 the Color-by-attribute dialog, which writes
+ * `jexl:randomColor(get(feature,'<attr>'))` 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;