@jbrowse/core 5.0.0-beta.8 → 5.0.0-beta.9

package/esm/util/installPrerequisiteFetch.js

@@ -1,4 +1,3 @@
-import { adapterConfigKey } from './adapterConfigKey.js';
 import { installFetch } from './installFetch.js';
 /**
  * A **prerequisite read**: one RPC about the adapter itself, beside the
@@ -36,7 +35,7 @@ import { installFetch } from './installFetch.js';
  *   nothing; a header is not a load.
  *
  * `createAdapterMetadataFetch` keys on the same adapter config and is
- * deliberately NOT one of these: no trigger, no stop token and no status,
+ * deliberately NOT one of these: no trigger, no signal and no status,
  * because it is fetched lazily when a details widget opens and the widget opens
  * on the result. A prerequisite read is the one a display's own fetch waits on.
  *
@@ -53,7 +52,7 @@ import { installFetch } from './installFetch.js';
  * Everything the skeleton gives it is the point of going through the skeleton:
  * the latest-wins rotation (so a superseding read aborts the one it replaced,
  * and only a superseding read does — a user cancel of the primary fetch cannot
- * strand the display the way sharing its token would), the clear at the start,
+ * strand the display the way sharing its signal would), the clear at the start,
  * the currency-guarded error rule, the unconditional `reloadCounter` read that
  * makes the chrome's Retry re-run this, and the retired status slot that keeps a
  * failed read from leaving a progress chip up for good.
@@ -65,7 +64,7 @@ export function installPrerequisiteFetch(self, { name, delay, report, gate = ()
         report,
         gate: () => !self.isMinimized && gate(),
         prepare: () => ({ adapterConfig: self.adapterConfig }),
-        fetchKey: ({ adapterConfig }) => adapterConfigKey(adapterConfig),
+        fetchKey: ({ adapterConfig }) => adapterConfig,
         run: ({ adapterConfig }, ctx) => run(adapterConfig, ctx),
         commit,
         setError,

package/esm/util/io/index.js

@@ -19,11 +19,14 @@ export function resolveUriLocation(location) {
         : location;
 }
 /**
- * The local path a `file:` URI names, or undefined for any other scheme. A
- * Windows URL parses as `/C:/data/x.bam`, whose leading slash is part of the URL
- * grammar rather than the path.
+ * The local path a `file:` URI or a bare absolute path names, or undefined for
+ * anything else. A Windows URL parses as `/C:/data/x.bam`, whose leading slash
+ * is part of the URL grammar rather than the path.
  */
-function fileUrlToLocalPath(uri) {
+function uriToLocalPath(uri) {
+    if (uri.startsWith('/') || /^[a-z]:[\\/]/i.test(uri)) {
+        return uri;
+    }
     if (!uri.startsWith('file:')) {
         return undefined;
     }
@@ -82,14 +85,11 @@ export function openLocation(location, pluginManager) {
         // a config that names its files relative to itself found no account at all
         // and read every one of them unauthenticated.
         const absoluteLocation = resolveUriLocation(location);
-        // A file: URI names a path on this machine, not something to fetch. Desktop
-        // reaches this by way of the shorthand forms: a config.json opened from disk
-        // carries a baseUri of its own directory, so `{ type: 'BamAdapter', uri:
-        // 'reads.bam' }` resolves here as file:///dir/reads.bam — and so does every
-        // sibling the shorthand derived from it (.bai, .fai, .gzi). Reading them as
-        // localPath keeps that whole chain on the one code path that can open a
-        // local file, instead of a fetch that no range request survives.
-        const localPath = fileUrlToLocalPath(absoluteLocation.uri);
+        // A file: URI or a bare absolute path names a file on this machine. A
+        // config.json opened from disk resolves `uri: 'reads.bam'` against its own
+        // directory to file:///dir/reads.bam, and a session built over MCP writes
+        // `uri: '/dir/reads.bam'` with no baseUri at all; fetched, either is a 404.
+        const localPath = uriToLocalPath(absoluteLocation.uri);
         if (localPath !== undefined && (isNode || isElectron)) {
             return openLocation({ localPath, locationType: 'LocalPathLocation' });
         }

package/esm/util/isDataCurrent.d.ts

@@ -1,7 +1,9 @@
 /**
- * The signature-based analog of the spatial `viewportWithinLoadedData`
- * (MultiRegionDisplayMixin) freshness check, for a display whose liveness is one
- * string rather than a per-region coverage map. An `undefined` loaded signature
- * is nothing fetched yet, so never current.
+ * Whether the key held data was committed under still equals the key a fetch
+ * issued now would carry. Keys are values compared structurally, so a stamp
+ * that kept its identity short-circuits on `===`, and an `undefined`-valued
+ * field or a fieldless class instance is still a distinct state — the two
+ * shapes `JSON.stringify` flattened. An `undefined` loaded key is nothing
+ * fetched yet, so never current.
  */
-export declare function isDataCurrent(loadedSignature: string | undefined, currentSignature: string | undefined): boolean;
+export declare function isDataCurrent(loaded: unknown, current: unknown): boolean;

package/esm/util/isDataCurrent.js

@@ -1,9 +1,12 @@
+import { compareStructural } from 'mobx';
 /**
- * The signature-based analog of the spatial `viewportWithinLoadedData`
- * (MultiRegionDisplayMixin) freshness check, for a display whose liveness is one
- * string rather than a per-region coverage map. An `undefined` loaded signature
- * is nothing fetched yet, so never current.
+ * Whether the key held data was committed under still equals the key a fetch
+ * issued now would carry. Keys are values compared structurally, so a stamp
+ * that kept its identity short-circuits on `===`, and an `undefined`-valued
+ * field or a fieldless class instance is still a distinct state — the two
+ * shapes `JSON.stringify` flattened. An `undefined` loaded key is nothing
+ * fetched yet, so never current.
  */
-export function isDataCurrent(loadedSignature, currentSignature) {
-    return loadedSignature !== undefined && loadedSignature === currentSignature;
+export function isDataCurrent(loaded, current) {
+    return loaded !== undefined && compareStructural(loaded, current);
 }

package/esm/util/jexl.js

@@ -1,23 +1,10 @@
 import { Jexl } from '@jbrowse/jexl';
+import { categoricalColor } from '../ui/colors.js';
 import { randomColor } from './color/index.js';
 import { colord } from './colord.js';
 import { jexlFeatureProxy, unwrapFeature } from './simpleFeature.js';
 export default function JexlF( /* config?: any*/) {
     const j = new Jexl();
-    // Memoize compilation on the instance itself. A compiled Expression closes
-    // over this instance's grammar (its registered functions), so the cache
-    // belongs here and is naturally per-instance — there is no shared cache that
-    // could bind an expression to the wrong instance's functions.
-    const rawCompile = j.compile.bind(j);
-    const cache = new Map();
-    j.compile = (code) => {
-        let expr = cache.get(code);
-        if (expr === undefined) {
-            expr = rawCompile(code);
-            cache.set(code, expr);
-        }
-        return expr;
-    };
     // someday will make sure all of configs callbacks are added in, including
     // ones passed in
     // below are core functions
@@ -31,15 +18,29 @@ export default function JexlF( /* config?: any*/) {
         return p ? jexlFeatureProxy(p) : undefined;
     });
     j.addFunction('id', (feature) => unwrapFeature(feature).id());
+    /**
+     * #jexlFunction Feature operations - getInherited | getInherited(feature, 'gene_biotype') | the attribute from the feature, or from its nearest ancestor that has it, so a CDS reads its gene's value
+     */
+    j.addFunction('getInherited', (feature, name) => {
+        let cur = unwrapFeature(feature);
+        while (cur !== undefined) {
+            const value = cur.get(name);
+            if (value !== undefined) {
+                return value;
+            }
+            cur = cur.parent?.();
+        }
+        return undefined;
+    });
     // let user cast a jexl type into a javascript type
     j.addFunction('cast', (arg) => arg);
-    // math
-    // addfunction added in jexl 2.3 but types/jexl still on 2.2
-    /** #jexlFunction Math functions | max(0, 2) */
-    j.addFunction('max', Math.max);
-    /** #jexlFunction Math functions | min(0, 2) */
-    j.addFunction('min', Math.min);
-    /** #jexlFunction Math functions | sqrt(4) */
+    // jexl's own list-aware min and max take varargs too; a Math.min
+    // registration would replace them
+    /**
+     * #jexlFunction Math functions | max(0, 2)
+     * #jexlFunction Math functions | min(feature.INFO.AF)
+     * #jexlFunction Math functions | sqrt(4)
+     */
     j.addFunction('sqrt', Math.sqrt);
     /** #jexlFunction Math functions | ceil(0.5) */
     j.addFunction('ceil', Math.ceil);
@@ -148,6 +149,8 @@ export default function JexlF( /* config?: any*/) {
     // color helpers
     /** #jexlFunction Color functions | randomColor(feature.type) | deterministic color from a string (e.g. a feature type) */
     j.addFunction('randomColor', randomColor);
+    /** #jexlFunction Color functions | categoricalColor(getInherited(feature, 'biotype'), ['protein_coding']) | a palette color per value: the values listed take the palette (an optional third argument) in order, any other value a stable color no listed value paints, a missing one grey */
+    j.addFunction('categoricalColor', categoricalColor);
     // These take and return CSS color *strings*, not Colord objects: a config
     // `jexl:` expression has no way to construct a Colord, and a color slot
     // holding one resolves to the invalid-color sentinel rather than a color. So

package/esm/util/jexlFilterRows.d.ts

@@ -0,0 +1,89 @@
+import type { AstNode, Subject } from '@jbrowse/jexl';
+export type JexlFilterFieldType = 'number' | 'text' | 'flag';
+export type JexlFilterField = {
+    label: string;
+    /** unset for a field whose values may be numbers or text */
+    type?: JexlFilterFieldType;
+    group?: string;
+    description?: string;
+    /** holds several values per feature, so a comparison asks whether any does */
+    multi?: boolean;
+    values?: string[];
+} & ({
+    path: string[];
+} | {
+    call: string;
+});
+export interface FieldChoice {
+    key: string;
+    label: string;
+    type?: JexlFilterFieldType;
+    subject: Subject;
+    group?: string;
+    description?: string;
+    multi?: boolean;
+    values?: string[];
+}
+export type RowOp = '>' | '>=' | '<' | '<=' | '==' | '!=' | 'in' | '~' | 'set' | '!set';
+export declare const OPERATORS: Record<JexlFilterFieldType | 'any', {
+    op: RowOp;
+    label: string;
+}[]>;
+export interface ConditionRow {
+    kind: 'condition';
+    id: number;
+    line?: number;
+    field?: FieldChoice;
+    op: RowOp;
+    value: string | string[];
+}
+export interface TextRow {
+    kind: 'text';
+    id: number;
+    line?: number;
+    text: string;
+}
+export type FilterRow = ConditionRow | TextRow;
+/**
+ * Rows keep the index of the stored line they came from until one of that
+ * line's rows changes, so an untouched line is written back byte-identical.
+ */
+export interface FilterRows {
+    lines: readonly string[];
+    rows: FilterRow[];
+}
+interface Parser {
+    parse: (text: string) => AstNode | null;
+}
+export declare function resolveFields(fields: readonly JexlFilterField[]): {
+    key: string;
+    label: string;
+    type: JexlFilterFieldType | undefined;
+    group: string | undefined;
+    description: string | undefined;
+    multi: boolean | undefined;
+    values: string[] | undefined;
+    subject: Subject;
+}[];
+/**
+ * The columns an adapter's metadata describes as `{column: description}`, as
+ * a BigBed's autoSql does, less those `fields` already lists. Any other
+ * metadata describes none.
+ */
+export declare function describedColumns(metadata: unknown, fields: readonly JexlFilterField[]): JexlFilterField[];
+/** A field typed into the picker rather than chosen, read as a dotted path. */
+export declare function typedField(text: string): FieldChoice;
+export declare function stripJexlPrefix(line: string): string;
+export declare function readFilterRows(lines: readonly string[], parser: Parser, choices: readonly FieldChoice[]): FilterRows;
+export declare function addRow(state: FilterRows): FilterRows;
+export declare function replaceRow(state: FilterRows, row: FilterRow): FilterRows;
+export declare function removeRow(state: FilterRows, id: number): FilterRows;
+export declare function withField(row: ConditionRow, field: FieldChoice): ConditionRow;
+export declare function withOp(row: ConditionRow, op: RowOp): ConditionRow;
+/**
+ * The stored filters: an untouched line as it was, and every row of an edited
+ * line as a line of its own, which is equivalent because lines AND together.
+ * Rows left incomplete are dropped.
+ */
+export declare function writeFilterRows({ lines, rows }: FilterRows): string[];
+export {};

package/esm/util/jexlFilterRows.js

@@ -0,0 +1,252 @@
+import { callSubject, conditions, pathSubject, print, printCondition, } from '@jbrowse/jexl';
+import { JEXL_PREFIX, ensureJexlPrefix, isJexl } from './jexlStrings.js';
+export const OPERATORS = {
+    number: [
+        { op: '>', label: '>' },
+        { op: '>=', label: '≥' },
+        { op: '<', label: '<' },
+        { op: '<=', label: '≤' },
+        { op: '==', label: '=' },
+        { op: '!=', label: '≠' },
+    ],
+    text: [
+        { op: '==', label: 'is' },
+        { op: '!=', label: 'is not' },
+        { op: 'in', label: 'is one of' },
+        { op: '~', label: 'matches' },
+    ],
+    flag: [
+        { op: 'set', label: 'is set' },
+        { op: '!set', label: 'is not set' },
+    ],
+    any: [
+        { op: '==', label: 'is' },
+        { op: '!=', label: 'is not' },
+        { op: '>', label: '>' },
+        { op: '>=', label: '≥' },
+        { op: '<', label: '<' },
+        { op: '<=', label: '≤' },
+        { op: 'in', label: 'is one of' },
+        { op: '~', label: 'matches' },
+    ],
+};
+const ROW = 'feature';
+function subjectKey(subject) {
+    return JSON.stringify(subject.kind === 'path'
+        ? ['path', ...subject.path]
+        : ['call', subject.name, ...subject.args]);
+}
+export function resolveFields(fields) {
+    return fields.map(({ label, type, group, description, multi, values, ...source }) => {
+        const subject = 'call' in source
+            ? callSubject(ROW, source.call)
+            : pathSubject(ROW, source.path);
+        return {
+            key: subjectKey(subject),
+            label,
+            type,
+            group,
+            description,
+            multi,
+            values,
+            subject,
+        };
+    });
+}
+// a feature carries these as refName, start and end
+const BED_LOCUS_COLUMNS = new Set(['chrom', 'chromStart', 'chromEnd']);
+/**
+ * The columns an adapter's metadata describes as `{column: description}`, as
+ * a BigBed's autoSql does, less those `fields` already lists. Any other
+ * metadata describes none.
+ */
+export function describedColumns(metadata, fields) {
+    const entries = metadata && typeof metadata === 'object' ? Object.entries(metadata) : [];
+    const listed = new Set(fields.map(field => field.label));
+    return entries.every((entry) => typeof entry[1] === 'string')
+        ? entries
+            .filter(([name]) => !listed.has(name) && !BED_LOCUS_COLUMNS.has(name))
+            .map(([name, description]) => ({
+            label: name,
+            path: [name],
+            description: description || undefined,
+        }))
+        : [];
+}
+/** A field typed into the picker rather than chosen, read as a dotted path. */
+export function typedField(text) {
+    const subject = pathSubject(ROW, text.split('.'));
+    return { key: subjectKey(subject), label: text, subject };
+}
+export function stripJexlPrefix(line) {
+    return isJexl(line) ? line.slice(JEXL_PREFIX.length) : line;
+}
+/** A field of no known type writes a value that reads as a number as one. */
+function scalar(type, text) {
+    const number = Number(text);
+    return type === 'number' ||
+        (!type && text.trim() !== '' && Number.isFinite(number))
+        ? number
+        : text;
+}
+function subjectLabel(subject) {
+    return subject.kind === 'path'
+        ? subject.path
+            .map((key, i) => typeof key === 'number' ? `[${key}]` : i === 0 ? key : `.${key}`)
+            .join('')
+        : print(subject.node);
+}
+function conditionRow(c, choices, id, line) {
+    const value = 'value' in c ? c.value : undefined;
+    const key = subjectKey(c.subject);
+    const field = choices.find(f => f.key === key) ?? {
+        key,
+        label: subjectLabel(c.subject),
+        type: value === undefined ? 'flag' : undefined,
+        subject: c.subject,
+    };
+    const op = c.op;
+    const values = value === undefined ? [] : [value].flat();
+    const writesBack = (v) => op === '~' ? typeof v === 'string' : scalar(field.type, String(v)) === v;
+    return OPERATORS[field.type ?? 'any'].some(o => o.op === op) &&
+        values.every(writesBack)
+        ? {
+            kind: 'condition',
+            id,
+            line,
+            field,
+            op,
+            value: Array.isArray(value) ? value.map(String) : String(value ?? ''),
+        }
+        : undefined;
+}
+function parseConditions(text, parser, calls) {
+    try {
+        return conditions(parser.parse(text), {
+            row: ROW,
+            accessors: { get: [] },
+            calls,
+        });
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readFilterRows(lines, parser, choices) {
+    const calls = choices.flatMap(f => f.subject.kind === 'call' ? [f.subject.name] : []);
+    const rows = [];
+    for (const [line, stored] of lines.entries()) {
+        const text = stripJexlPrefix(stored);
+        const id = rows.length;
+        const read = parseConditions(text, parser, calls)?.map((c, i) => conditionRow(c, choices, id + i, line));
+        rows.push(...(read?.every(row => row !== undefined)
+            ? read
+            : [{ kind: 'text', id, line, text: text.trim() }]));
+    }
+    return { lines, rows };
+}
+function nextId(rows) {
+    return rows.reduce((max, row) => Math.max(max, row.id + 1), 0);
+}
+function emptyRow(id) {
+    return { kind: 'condition', id, op: '==', value: '' };
+}
+export function addRow(state) {
+    return { ...state, rows: [...state.rows, emptyRow(nextId(state.rows))] };
+}
+function detach(rows, id) {
+    const line = rows.find(row => row.id === id)?.line;
+    return line === undefined
+        ? rows
+        : rows.map(row => (row.line === line ? { ...row, line: undefined } : row));
+}
+export function replaceRow(state, row) {
+    return {
+        ...state,
+        rows: detach(state.rows, row.id).map(r => r.id === row.id ? { ...row, line: undefined } : r),
+    };
+}
+export function removeRow(state, id) {
+    return {
+        ...state,
+        rows: detach(state.rows, id).filter(row => row.id !== id),
+    };
+}
+export function withField(row, field) {
+    const sameType = row.field?.type === field.type;
+    const ops = OPERATORS[field.type ?? 'any'];
+    return {
+        ...row,
+        field,
+        op: sameType ? row.op : ops[0].op,
+        value: sameType ? row.value : '',
+    };
+}
+export function withOp(row, op) {
+    const { value } = row;
+    return {
+        ...row,
+        op,
+        value: op === 'in'
+            ? Array.isArray(value)
+                ? value
+                : value
+                    ? [value]
+                    : []
+            : Array.isArray(value)
+                ? (value[0] ?? '')
+                : value,
+    };
+}
+function writeCondition({ field, op, value }) {
+    if (!field) {
+        return undefined;
+    }
+    const { subject, type } = field;
+    const usable = (v) => v.trim() !== '' && (type !== 'number' || Number.isFinite(Number(v)));
+    if (op === 'set' || op === '!set') {
+        return printCondition({ subject, op });
+    }
+    if (op === 'in') {
+        const list = [value].flat().filter(usable);
+        return list.length > 0
+            ? printCondition({
+                subject,
+                op,
+                value: list.map(v => scalar(type, v)),
+            })
+            : undefined;
+    }
+    const text = [value].flat()[0] ?? '';
+    return !usable(text)
+        ? undefined
+        : op === '~'
+            ? printCondition({ subject, op, value: text })
+            : printCondition({ subject, op, value: scalar(type, text) });
+}
+function writeRow(row) {
+    const text = row.kind === 'text' ? row.text.trim() || undefined : writeCondition(row);
+    return text === undefined ? undefined : ensureJexlPrefix(text);
+}
+/**
+ * The stored filters: an untouched line as it was, and every row of an edited
+ * line as a line of its own, which is equivalent because lines AND together.
+ * Rows left incomplete are dropped.
+ */
+export function writeFilterRows({ lines, rows }) {
+    const out = [];
+    let previous;
+    for (const row of rows) {
+        if (row.line === undefined) {
+            const text = writeRow(row);
+            if (text !== undefined) {
+                out.push(text);
+            }
+        }
+        else if (row.line !== previous) {
+            out.push(lines[row.line]);
+        }
+        previous = row.line;
+    }
+    return out;
+}

package/esm/util/jexlFilters.d.ts

@@ -4,11 +4,13 @@ import type { Reversible } from '../ui/filterMenuItems.ts';
  * The two-tier feature-filter contract, shared by every display offering a
  * "Filter by..." row. Two tiers because the setting has two authors:
  *
- * - the **`jexlFilters` config slot** on `baseLinearDisplayConfigSchema`, which
- *   an admin declares in a track config. It stores expressions **unprefixed**,
- *   because config-slot values are deferred-evaluation and a stored `jexl:` is
- *   what marks a slot as a callback — so the prefix goes on at read time, in
- *   `configuredJexlFilters`.
+ * - the **`jexlFilters` config slot**, which an admin declares in a track
+ *   config. It stores expressions **unprefixed**, because config-slot values
+ *   are deferred-evaluation and a stored `jexl:` is what marks a slot as a
+ *   callback — so the prefix goes on at read time, in `configuredJexlFilters`.
+ *   The slot is `jexlFilterConfigSchemaFields` in display-kit, spread by the
+ *   canvas base display schema, the mark display schema and the shared
+ *   multi-sample variant schema — the three whose models read it.
  * - the **`jexlFiltersSetting` display property**, which the dialog writes and
  *   which stores them already prefixed (the runtime convention). Set — *even to
  *   an empty list* — it replaces the config tier entirely, which is what makes

package/esm/util/jexlStrings.d.ts

@@ -1,6 +1,6 @@
 export interface JexlExpression {
     eval(context?: Record<string, unknown>): unknown;
-    _exprStr?: string;
+    readonly source?: string;
 }
 export interface JexlInstance {
     compile(code: string): JexlExpression;
@@ -11,9 +11,8 @@ export declare function isJexl(str: unknown): str is string;
 /** Add the `jexl:` prefix unless the string already carries it. */
 export declare function ensureJexlPrefix(code: string): string;
 /**
- * Compile a `jexl:...` string to an Expression. Compilation is memoized on the
- * jexl instance (see `createJexlInstance`), so this is a thin prefix-stripping
- * wrapper.
+ * Compile a `jexl:...` string to an Expression. The jexl instance caches
+ * compilation, so this only strips the prefix.
  *
  * @param str - string of code like `jexl:...`
  * @param jexl - the instance whose registered functions the expression may call

package/esm/util/jexlStrings.js

@@ -8,9 +8,8 @@ export function ensureJexlPrefix(code) {
     return isJexl(code) ? code : `${JEXL_PREFIX}${code}`;
 }
 /**
- * Compile a `jexl:...` string to an Expression. Compilation is memoized on the
- * jexl instance (see `createJexlInstance`), so this is a thin prefix-stripping
- * wrapper.
+ * Compile a `jexl:...` string to an Expression. The jexl instance caches
+ * compilation, so this only strips the prefix.
  *
  * @param str - string of code like `jexl:...`
  * @param jexl - the instance whose registered functions the expression may call

package/esm/util/legendCandidates.d.ts

@@ -1,31 +1,26 @@
+import type { ColorScale } from '../ui/colorScale.ts';
+import type { CategoricalField } from './categoricalField.ts';
 export interface LegendCandidate {
     rowIndex: number;
-    label: string;
+    value: string;
     color: number;
 }
 export interface LegendEntry {
-    label: string;
+    values: string[];
     color: number;
 }
 export declare const MAX_LEGEND_ENTRIES = 30;
 export declare const MAX_LEGEND_CANDIDATES = 1024;
 /**
- * Accumulator for the distinct (row, name, color) combinations a packer walks
- * past, in first-seen order and bounded — the small list `unionLegendCandidates`
- * derives a key from, so the main thread never re-walks the features. Fed scalar
- * by scalar, from the loop that already holds the three values.
- *
- * Deduped on the whole triple rather than on (row, color): the union takes the
- * first NAME it sees for a color, so where that name is already spoken for, the
- * second name on that color has to still be in the list to carry it.
- *
- * A nameless feature contributes nothing, which is the union's rule too — so a
- * track whose features have no names ships an empty list rather than one entry
- * per feature.
+ * Accumulator for the distinct (row, value, color) combinations a packer walks
+ * past, in first-seen order and bounded, so the main thread never re-walks the
+ * features. Deduped on the whole triple: a row of the union lists every value
+ * painted in its color, so a second value on that color has to still be in the
+ * list to reach it.
  */
 export declare function createLegendCandidateCollector(maxCandidates?: number): {
     candidates: LegendCandidate[];
-    add(rowIndex: number, label: string, color: number): void;
+    add(rowIndex: number, value: string, color: number): void;
 };
 export interface LegendCandidateSource {
     candidates: readonly LegendCandidate[];
@@ -33,18 +28,27 @@ export interface LegendCandidateSource {
 }
 /**
  * The categorical color key over any number of packed regions: one entry per
- * distinct color, labeled by the first name seen in that color, in first-seen
- * order.
- *
- * Keyed by color rather than by name, so each key row is 1:1 with a color — a
- * row is normally a toggle and hiding a category hides features BY color, so two
- * names sharing one color must collapse to a single row. A name reused across
- * two colors keeps its first-seen color.
+ * distinct color listing every value painted in it, colors in first-seen
+ * order. Keyed by color rather than by value because hiding a category hides
+ * features BY color, so two values sharing one color are one row that names
+ * both; a value met in two colors stays with the first.
  *
- * `[]` when the data carries no categorical signal: nothing named, or more than
- * `maxEntries` distinct colors.
- *
- * `regions` is consumed lazily, so a caller able to answer without reading any
- * of them can pass a generator and have none of them touched.
+ * `[]` when there are more than `maxEntries` distinct colors, where the data is
+ * not a categorical vocabulary. `regions` is consumed lazily.
  */
 export declare function unionLegendCandidates<T>(regions: Iterable<T>, resolve: (region: T) => LegendCandidateSource, maxEntries?: number): LegendEntry[];
+/**
+ * The one categorical key a color channel derives from what a worker painted:
+ * the union above over the loaded regions, each row a painted color naming
+ * every value in it through `field` and ordered by it, and nothing where the
+ * rows would say nothing (`legendIsReadable`). A display resolving its own colors hands the
+ * candidates its packer recorded; one resolved by `encodeFeatures` hands the
+ * entries of the scale tables that came back. Either way the key lists what
+ * the painting holds, and a `closed` field's domain besides once anything
+ * painted.
+ */
+export declare function derivedColorScale<T>(regions: Iterable<T>, resolve: (region: T) => LegendCandidateSource, { id, field, maxItems, }: {
+    id: string;
+    field: CategoricalField;
+    maxItems?: number;
+}): ColorScale[];