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

package/esm/util/featureTypes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Classification of a feature from its `type` string alone, for the plugins
+ * that decide something about a feature they did not parse. A type is the only
+ * thing a display, a menu or a widget can ask about a feature without knowing
+ * which adapter produced it, so these live in core rather than beside any one
+ * of their callers.
+ */
+/**
+ * Whether the type names a unit of transcription — a gene, a transcript, or an
+ * RNA, including the pseudogene and V(D)J segment spellings. This is the
+ * question "does this feature have exons", not "can this feature be spliced":
+ * an alignment splices too and is deliberately not gene-like, because a caller
+ * that means to launch a protein view or read a CDS would be wrong about it.
+ */
+export declare function isGeneLikeType(type: string | undefined): boolean;
+/**
+ * Whether the type names a sequence alignment — SO `match` and its subtypes
+ * (`cDNA_match`, `EST_match`, `nucleotide_match`, `protein_match`,
+ * `translated_nucleotide_match`), whose `match_part` children are the aligned
+ * blocks and whose gaps between them are introns when the aligned sequence was
+ * a transcript. Separate from `isGeneLikeType` on purpose: an EST alignment is
+ * evidence for a gene, not one.
+ */
+export declare function isSequenceMatchType(type: string | undefined): boolean;

package/esm/util/featureTypes.js

@@ -0,0 +1,35 @@
+/**
+ * Classification of a feature from its `type` string alone, for the plugins
+ * that decide something about a feature they did not parse. A type is the only
+ * thing a display, a menu or a widget can ask about a feature without knowing
+ * which adapter produced it, so these live in core rather than beside any one
+ * of their callers.
+ */
+// Anchored at the end so 'intergenic_region' is not a gene, 'rnapol_binding_site'
+// is not an RNA, and 'transcriptional_cis_regulatory_region' is not a
+// transcript.
+const GENE_LIKE_TYPE = /gene(_segment)?$|rna$|transcript$/;
+/**
+ * Whether the type names a unit of transcription — a gene, a transcript, or an
+ * RNA, including the pseudogene and V(D)J segment spellings. This is the
+ * question "does this feature have exons", not "can this feature be spliced":
+ * an alignment splices too and is deliberately not gene-like, because a caller
+ * that means to launch a protein view or read a CDS would be wrong about it.
+ */
+export function isGeneLikeType(type) {
+    return type !== undefined && GENE_LIKE_TYPE.test(type.toLowerCase());
+}
+// SO `match` and every subtype of it is spelled `<something>_match`, so the
+// suffix is the family. `match_part`, the child, is excluded by the anchor.
+const SEQUENCE_MATCH_TYPE = /(^|_)match$/;
+/**
+ * Whether the type names a sequence alignment — SO `match` and its subtypes
+ * (`cDNA_match`, `EST_match`, `nucleotide_match`, `protein_match`,
+ * `translated_nucleotide_match`), whose `match_part` children are the aligned
+ * blocks and whose gaps between them are introns when the aligned sequence was
+ * a transcript. Separate from `isGeneLikeType` on purpose: an EST alignment is
+ * evidence for a gene, not one.
+ */
+export function isSequenceMatchType(type) {
+    return type !== undefined && SEQUENCE_MATCH_TYPE.test(type.toLowerCase());
+}

package/esm/util/fetchAndMaybeUnzip.js

@@ -1,6 +1,8 @@
 import { redactSource } from './getLocationUri.js';
 import { downloadStatus, phaseOf, updateStatus } from './progress.js';
-import { withStopTokenSignal } from './stopToken.js';
+function loadInflater() {
+    return import('@gmod/bgzf-filehandle');
+}
 export function isGzip(buf) {
     return buf[0] === 31 && buf[1] === 139 && buf[2] === 8;
 }
@@ -36,22 +38,27 @@ label = 'Downloading file') {
     const phase = loc.source === undefined
         ? label
         : { message: phaseOf(label), source: redactSource(loc.source) };
-    const { statusCallback, stopToken } = opts;
-    // the stop token becomes the read's signal, so a cancelled whole-file load
-    // drops at the socket rather than downloading a multi-GB body to completion
-    const buf = await withStopTokenSignal(stopToken, signal => downloadStatus(phase, statusCallback, onProgress => loc.readFile({ ...opts, onProgress, signal })));
+    const { statusCallback, signal } = opts;
     // the inflater is imported dynamically because this module is reachable from
     // the core/util barrel, so a static import put bgzf-filehandle + pako
-    // (~180KB) on the startup path of every page load; only an actually-gzipped
-    // file needs them
+    // (~180KB) on the startup path of every page load. A name ending .gz starts
+    // that import beside the download instead of after it; the bytes still decide
+    // whether to inflate.
+    const inflater = /\.gz($|[?#])/.test(loc.source ?? '')
+        ? loadInflater()
+        : undefined;
+    inflater?.catch(() => { });
+    // the signal reaches the read, so a cancelled whole-file load drops at the
+    // socket rather than downloading a multi-GB body to completion
+    const buf = await downloadStatus(phase, statusCallback, onProgress => loc.readFile({ ...opts, onProgress, signal }));
     return isGzip(buf)
         ? await updateStatus('Unzipping', statusCallback, async () => {
-            const { unzip } = await import('@gmod/bgzf-filehandle');
+            const { unzip } = await (inflater ?? loadInflater());
             return unzip(buf);
         }, 
         // a cancel landing here is otherwise discovered only by whatever parses
         // the result, after a whole-file inflate has run to completion
-        stopToken)
+        signal)
         : buf;
 }
 export async function fetchAndMaybeUnzipText(loc, opts, label) {

package/esm/util/fetchContext.d.ts

@@ -1,9 +1,8 @@
 import type { RpcCallArgs, RpcCallReturn } from '../rpc/RpcRegistry.ts';
 import type { StatusCallback } from './progress.ts';
-import type { StopToken } from './stopToken.ts';
 import type { IStateTreeNode } from '@jbrowse/mobx-state-tree';
 export interface FetchContext {
-    stopToken: StopToken;
+    signal: AbortSignal;
     isStale: () => boolean;
     /**
      * The RPC `statusCallback` for the work this context describes: guarded to
@@ -24,23 +23,23 @@ export interface FetchContext {
     /**
      * The one way a fetch calls an RPC: the registry-typed
      * `rpcManager.call(rpcSessionId, method, args)` with this context's
-     * `stopToken` and `statusCallback` injected. Both used to be hand-threaded
+     * `signal` and `statusCallback` injected. Both used to be hand-threaded
      * at every fetch site, and forgetting either was silent — no cancellation
      * for that display, or no progress — which is exactly the failure class the
      * envelope makes inexpressible: a fetch cannot issue an RPC the cancel and
      * the status bar don't know about.
      *
      * Declared with a `this` parameter so it reads the *holding* context's
-     * token and callback — the fan-out copies rebind it to their own status
+     * signal and callback — the fan-out copies rebind it to their own status
      * slot by construction — and so destructuring it off the context is a type
      * error rather than a stale binding.
      */
-    callRpc: <M extends string>(this: FetchContext, method: M, args: Omit<RpcCallArgs<M>, 'stopToken' | 'statusCallback'>) => Promise<RpcCallReturn<M>>;
+    callRpc: <M extends string>(this: FetchContext, method: M, args: Omit<RpcCallArgs<M>, 'signal' | 'statusCallback'>) => Promise<RpcCallReturn<M>>;
 }
 /**
  * Build a {@link FetchContext} over a live fetch's primitives. One
- * constructor, so every context — `runFetch`'s, the prerequisite skeleton's —
- * carries the same `callRpc` envelope.
+ * constructor, so every context — `FetchMixin.runFetch`'s and `runFetchOnce`'s
+ * alike — carries the same `callRpc` envelope.
  *
  * **`self` has to be somewhere `getRpcSessionId` can find one, which in practice
  * means a track or something under it.** `rpcSessionId` is declared by
@@ -52,7 +51,7 @@ export interface FetchContext {
  * track, which is what the breakpoint split view's overlay fetch does.
  */
 export declare function makeFetchContext(self: IStateTreeNode, base: {
-    stopToken: StopToken;
+    signal: AbortSignal;
     isStale: () => boolean;
     statusCallback: StatusCallback;
 }): FetchContext;

package/esm/util/fetchContext.js

@@ -3,8 +3,8 @@ import { createStatusFanOut } from './progress.js';
 import { getRpcHost } from './sessionServices.js';
 /**
  * Build a {@link FetchContext} over a live fetch's primitives. One
- * constructor, so every context — `runFetch`'s, the prerequisite skeleton's —
- * carries the same `callRpc` envelope.
+ * constructor, so every context — `FetchMixin.runFetch`'s and `runFetchOnce`'s
+ * alike — carries the same `callRpc` envelope.
  *
  * **`self` has to be somewhere `getRpcSessionId` can find one, which in practice
  * means a track or something under it.** `rpcSessionId` is declared by
@@ -21,7 +21,7 @@ export function makeFetchContext(self, base) {
         callRpc(method, args) {
             return getRpcHost(self).rpcManager.call(getRpcSessionId(self), method, {
                 ...args,
-                stopToken: this.stopToken,
+                signal: this.signal,
                 statusCallback: this.statusCallback,
             });
         },

package/esm/util/fetchHub.d.ts

@@ -1,6 +1,6 @@
 export interface HubConfig {
     assemblies?: Record<string, unknown>[];
-    aggregateTextSearchAdapters?: Record<string, unknown>[];
+    aggregateTextSearchAdapters?: (string | Record<string, unknown>)[];
     tracks?: Record<string, unknown>[];
     [key: string]: unknown;
 }
@@ -12,4 +12,6 @@ export declare function hubUrl(hub: string): string;
  * the name straight to `createLinearGenomeView({ assembly: 'hg38' })` for the
  * common case; call this directly only to cherry-pick tracks from the catalog.
  */
-export declare function fetchHub(hub: string): Promise<HubConfig>;
+export declare function fetchHub(hub: string, { signal }?: {
+    signal?: AbortSignal;
+}): Promise<HubConfig>;

package/esm/util/fetchHub.js

@@ -15,9 +15,9 @@ export function hubUrl(hub) {
  * the name straight to `createLinearGenomeView({ assembly: 'hg38' })` for the
  * common case; call this directly only to cherry-pick tracks from the catalog.
  */
-export async function fetchHub(hub) {
+export async function fetchHub(hub, { signal } = {}) {
     const url = hubUrl(hub);
-    const response = await fetch(url);
+    const response = await fetch(url, { signal });
     if (response.ok) {
         const config = (await response.json());
         // hosted configs reference their data relative to the config's own location

package/esm/util/fetchPhases.d.ts

@@ -4,10 +4,10 @@
  * remembered.
  *
  * The shared `installFetch` skeleton takes this shape, and so does the LGV
- * global family (`installGlobalFetchAutorun`, over `FetchMixin.runFetch`). It
- * was the same contract declared twice, with the same three rules explained
- * twice, which is a drift axis over rules whose whole value is being the same
- * everywhere.
+ * global family (`installGlobalFetchAutorun`, a declaration over that same
+ * skeleton). It was the same contract declared twice, with the same three rules
+ * explained twice, which is a drift axis over rules whose whole value is being
+ * the same everywhere.
  *
  * `TCtx` is what a family hands its `run`: a `FetchContext` for most of them, a
  * `ComparativeFetchContext` (that plus adapter config and refName rename) for
@@ -43,7 +43,7 @@ export interface FetchPhases<TArgs, TResult, TCtx> {
      * gets a dead Retry button — see there.
      *
      * What it must **not** do is move a trigger read of its own under a bail-out.
-     * See ARCHITECTURE.md §"The global-fetch trigger list must be read
+     * See reference/FETCH_SKELETON.md §"The global-fetch trigger list must be read
      * unconditionally".
      */
     prepare: () => TArgs | undefined;
@@ -56,11 +56,11 @@ export interface FetchPhases<TArgs, TResult, TCtx> {
      * **Nothing it reads is tracked**, so the payload it assembles cannot widen
      * the autorun's dependency set the way calling `rpcProps()` in the body would.
      * Being async is not what buys that — `run` is *called* synchronously, so its
-     * own prefix down to its first `await` runs wherever the caller was. Each
-     * family arranges it: the global one reaches `run` through
-     * `FetchMixin.runFetch`, an MST flow and so an action, which MobX runs
-     * untracked; the comparative one calls its lifecycle inside `untracked`
-     * because it has no action to hide behind.
+     * own prefix down to its first `await` runs wherever the caller was. The
+     * `installFetch` skeleton calls it inside `untracked`, which covers the
+     * global and comparative families with it; the per-region family reaches its
+     * work through `FetchMixin.runFetch`, an MST flow and so an action, which
+     * MobX runs untracked.
      */
     run: (args: TArgs, ctx: TCtx) => Promise<TResult | undefined>;
     /**

package/esm/util/fetchSeq.d.ts

@@ -1,12 +1,11 @@
 import type { StatusCallback } from './progress.ts';
-import type { StopToken } from './stopToken.ts';
 import type { AbstractSessionModel } from './types/index.ts';
-export declare function fetchSeq({ start, end, refName, assemblyName, session, stopToken, statusCallback, }: {
+export declare function fetchSeq({ start, end, refName, assemblyName, session, signal, statusCallback, }: {
     start: number;
     end: number;
     refName: string;
     assemblyName: string;
     session: AbstractSessionModel;
-    stopToken?: StopToken;
+    signal?: AbortSignal;
     statusCallback?: StatusCallback;
 }): Promise<string>;

package/esm/util/fetchSeq.js

@@ -1,5 +1,5 @@
 import { getSequenceAdapterConfig } from '../assemblyManager/getSequenceAdapterConfig.js';
-export async function fetchSeq({ start, end, refName, assemblyName, session, stopToken, statusCallback, }) {
+export async function fetchSeq({ start, end, refName, assemblyName, session, signal, statusCallback, }) {
     const { rpcManager, assemblyManager } = session;
     const assembly = await assemblyManager.waitForAssembly(assemblyName);
     if (!assembly) {
@@ -28,7 +28,7 @@ export async function fetchSeq({ start, end, refName, assemblyName, session, sto
             refName: seqAdapterRefName,
             assemblyName,
         },
-        stopToken,
+        signal,
         statusCallback,
     });
     return seq ?? '';

package/esm/util/fieldReader.d.ts

@@ -0,0 +1,17 @@
+import type { JexlInstance } from './jexlStrings.ts';
+import type { Feature } from './simpleFeature.ts';
+/**
+ * #api
+ * What a channel reads off a feature: a field by name, a dotted path into a
+ * structured field where no field carries the whole name (`INFO.SVTYPE` on a
+ * VCF record), or a `jexl:` expression over `feature`. A jexl expression that
+ * does not compile throws here, once, rather than on every feature.
+ */
+export declare function fieldReader(ref: string, jexl: JexlInstance | undefined): (feature: Feature) => unknown;
+/**
+ * #api
+ * Whether a field ref is a bare name: what `feature.get` answers on its own,
+ * with no path to walk and no expression to evaluate. A loop over a plain name
+ * keeps the direct call, and only a config that writes a path pays for one.
+ */
+export declare function isPlainFieldRef(ref: string): ref is never;

package/esm/util/fieldReader.js

@@ -0,0 +1,62 @@
+import { isJexl, stringToJexlExpression } from './jexlStrings.js';
+import { buildJexlContext } from './simpleFeature.js';
+/**
+ * #api
+ * What a channel reads off a feature: a field by name, a dotted path into a
+ * structured field where no field carries the whole name (`INFO.SVTYPE` on a
+ * VCF record), or a `jexl:` expression over `feature`. A jexl expression that
+ * does not compile throws here, once, rather than on every feature.
+ */
+export function fieldReader(ref, jexl) {
+    const path = ref.includes('.') ? ref.split('.') : undefined;
+    const rests = path?.map((_, i) => path.slice(i).join('.'));
+    if (isJexl(ref)) {
+        if (!jexl) {
+            throw new Error(`a jexl: field needs a jexl instance (${ref})`);
+        }
+        const expr = stringToJexlExpression(ref, jexl);
+        return feature => expr.eval(buildJexlContext({ feature }));
+    }
+    return feature => {
+        const value = feature.get(ref);
+        return value === undefined && path && rests
+            ? readPath(feature.get(path[0]), path, rests)
+            : value;
+    };
+}
+/**
+ * #api
+ * Whether a field ref is a bare name: what `feature.get` answers on its own,
+ * with no path to walk and no expression to evaluate. A loop over a plain name
+ * keeps the direct call, and only a config that writes a path pays for one.
+ */
+export function isPlainFieldRef(ref) {
+    return !ref.includes('.') && !isJexl(ref);
+}
+function readPath(root, path, rests) {
+    let value = root;
+    for (let i = 1; i < path.length; i++) {
+        value =
+            typeof value === 'object' && value !== null
+                ? Reflect.get(value, path[i])
+                : undefined;
+    }
+    return value ?? readWholeRest(root, path, rests);
+}
+// A path that read nothing by descending tries each level's rest as one key,
+// so `INFO.AF.EAS` reaches a key named `AF.EAS`, which VCF 4.3 allows. Only a
+// miss pays for it: a path that resolves is the plain walk above.
+function readWholeRest(root, path, rests) {
+    let value = root;
+    for (let i = 1; i < path.length - 1; i++) {
+        if (typeof value !== 'object' || value === null) {
+            return undefined;
+        }
+        const whole = Reflect.get(value, rests[i]);
+        if (whole !== undefined) {
+            return whole ?? undefined;
+        }
+        value = Reflect.get(value, path[i]);
+    }
+    return undefined;
+}

package/esm/util/freezeDeep.d.ts

@@ -1,20 +1,18 @@
 /**
  * Freeze `value` and everything reachable from it, in place, and return it.
  *
- * For a value handed to consumers **by reference on purpose**: a config slot's
- * `promotedBase` (the one literal every track sitting at base resolves to) and a
- * stored user preference (a promoted display-type default, read by every
- * following display). Sharing the reference is load-bearing in both cases —
- * `===` stability is what lets a display's cached MobX computed re-resolve
+ * For a value handed to consumers **by reference on purpose**: a stored user
+ * preference, read by everything that follows it. Sharing the reference is
+ * load-bearing — `===` stability is what lets a cached MobX computed re-derive
  * without waking anything downstream — so handing out a defensive copy per read
  * would trade a silent hazard for a real re-render on every read. Freezing keeps
  * the identity and makes "nothing mutates this" throw rather than quietly
- * rewriting a value every other track is reading.
+ * rewriting a value every other reader sees.
  *
- * Both callers freeze once, at schema build or at the store write, over a value
- * that has to survive `postMessage` anyway — so the recursion is over small JSON
- * and costs nothing per read. Cyclic input terminates: each object is frozen
- * before its children are visited.
+ * The caller freezes once, at the store write, over a value that has to survive
+ * `postMessage` anyway — so the recursion is over small JSON and costs nothing
+ * per read. Cyclic input terminates: each object is frozen before its children
+ * are visited.
  *
  * **Unconditional, deliberately unlike MST's own `deepFreeze`** (whose body this
  * otherwise mirrors), which is gated on `devMode()`. MST gates because it freezes

package/esm/util/freezeDeep.js

@@ -6,20 +6,18 @@ function isObjectLike(value) {
 /**
  * Freeze `value` and everything reachable from it, in place, and return it.
  *
- * For a value handed to consumers **by reference on purpose**: a config slot's
- * `promotedBase` (the one literal every track sitting at base resolves to) and a
- * stored user preference (a promoted display-type default, read by every
- * following display). Sharing the reference is load-bearing in both cases —
- * `===` stability is what lets a display's cached MobX computed re-resolve
+ * For a value handed to consumers **by reference on purpose**: a stored user
+ * preference, read by everything that follows it. Sharing the reference is
+ * load-bearing — `===` stability is what lets a cached MobX computed re-derive
  * without waking anything downstream — so handing out a defensive copy per read
  * would trade a silent hazard for a real re-render on every read. Freezing keeps
  * the identity and makes "nothing mutates this" throw rather than quietly
- * rewriting a value every other track is reading.
+ * rewriting a value every other reader sees.
  *
- * Both callers freeze once, at schema build or at the store write, over a value
- * that has to survive `postMessage` anyway — so the recursion is over small JSON
- * and costs nothing per read. Cyclic input terminates: each object is frozen
- * before its children are visited.
+ * The caller freezes once, at the store write, over a value that has to survive
+ * `postMessage` anyway — so the recursion is over small JSON and costs nothing
+ * per read. Cyclic input terminates: each object is frozen before its children
+ * are visited.
  *
  * **Unconditional, deliberately unlike MST's own `deepFreeze`** (whose body this
  * otherwise mirrors), which is gated on `devMode()`. MST gates because it freezes

package/esm/util/groupKeys.d.ts

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

package/esm/util/groupKeys.js

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