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

package/esm/pluggableElementTypes/models/expandTrackConfigShorthand.d.ts

@@ -1,39 +1,49 @@
 import type PluginManager from '../../PluginManager.ts';
+import type { AnyConfigurationSchemaType } from '../../configuration/index.ts';
 export interface DisplaySnapshot {
     type: string;
     displayId?: string;
     [key: string]: unknown;
 }
 /**
- * Pure: route each shorthand `displayDefaults: {...}` setting to the display
- * types that define it. A setting goes to every display type whose config schema
- * has that slot, so slot names disambiguate across displays on their own (e.g.
- * `color` → LinearVariantDisplay, `strokeColor` → ChordVariantDisplay). Keys no
- * display defines are returned as `unknownKeys` for the caller to surface.
+ * Route each shorthand `displayDefaults: {...}` setting to the display types
+ * whose member of that name takes its value: `color: 'red'` reaches every
+ * display with a colour, `color: { field: 'type' }` only those whose colour
+ * maps a field, and a spelling a display retired reaches that display as the
+ * members it became. `reached` names the displays each key went to. A key no
+ * display knows is an `unknownKeys` entry, and one every display that knows it
+ * refuses a `refused` entry carrying each reason.
  */
-export declare function collectDisplayOverrides(displaySettings: Record<string, unknown>, displaySlots: Map<string, Set<string>>): {
+export declare function collectDisplayOverrides(displaySettings: Record<string, unknown>, displaySchemas: ReadonlyMap<string, AnyConfigurationSchemaType>): {
     overrides: Map<string, Record<string, unknown>>;
+    reached: Map<string, string[]>;
     unknownKeys: string[];
+    refused: {
+        key: string;
+        reasons: string[];
+    }[];
 };
 /**
- * Pure: fold per-display override props into a `displays` array, creating an
- * entry (with a derived displayId) for any display type not already present.
- * Explicit entries in the existing array win over shorthand on conflict.
+ * Fold per-display override props into the entries a `displays` array already
+ * has; explicit props win. A display with no entry gets none: a setting never
+ * adds a display to a track.
  */
-export declare function mergeOverridesIntoDisplays(displays: DisplaySnapshot[], overrides: Map<string, Record<string, unknown>>, trackId: string): DisplaySnapshot[];
+export declare function mergeOverridesIntoDisplays(displays: DisplaySnapshot[], overrides: Map<string, Record<string, unknown>>): DisplaySnapshot[];
 /**
  * Expands the shorthand `displayDefaults` **object** into the explicit `displays`
  * **array**, so users can set display settings without naming the display type
  * or nesting in `displays:[{type,...}]`. `displayDefaults:{color:'green'}` routes
- * each setting to the display type(s) that define that slot, folding them into
- * whatever `displays` array the track already has (explicit entries win).
+ * each setting to the display type(s) whose slot takes it, folding them into
+ * the entries the `displays` array has (explicit props win). A key whose every
+ * taker is missing from the array, a display the track's adapter cannot feed,
+ * is reported rather than giving the track that display.
  *
  * `displayDefaults` is kept separate from `displays` (rather than overloading
  * `displays` by shape) so a config using it still loads in a JBrowse version
  * that predates the feature — the unknown key is ignored, instead of crashing
  * when the array-typed `displays` slot receives an object.
  *
- * Runs inside `baseTrackConfig.preProcessSnapshot`, before display-stub
+ * Runs inside `baseTrackConfig.preProcessSnapshot`, after display-stub
  * injection. Takes/returns the loosely-typed snapshot (as `evaluateExtensionPoint`
  * does) — the caller casts the result to its snapshot type for validation.
  */

package/esm/pluggableElementTypes/models/expandTrackConfigShorthand.js

@@ -1,75 +1,96 @@
 import { getConfigurationSchemaMetadata } from '../../configuration/schemaRegistry.js';
-function schemaSlotNames(schema) {
+import { slotValueRefusal } from '../../configuration/slotFacade.js';
+import { isPlainObject } from '../../util/objectUtils.js';
+/**
+ * What one display would do with a shorthand setting: the members it would
+ * write, or why it will not take it. `undefined` means the display has no
+ * member of that name and no retired spelling of one, so it is not a candidate
+ * and the key is not its business.
+ */
+function verdictOf(schema, key, value) {
     const meta = getConfigurationSchemaMetadata(schema);
-    return new Set(meta ? Object.keys(meta.definition) : []);
-}
-function isPlainObject(v) {
-    return typeof v === 'object' && v !== null && !Array.isArray(v);
-}
-/** display type name → its config slot names, for one track type. */
-function trackDisplaySlots(trackType) {
-    const displaySlots = new Map();
-    for (const d of trackType.displayTypes) {
-        displaySlots.set(d.name, schemaSlotNames(d.configSchema));
+    const retired = meta?.options.retired?.[key];
+    let members;
+    try {
+        members = retired
+            ? retired(value)
+            : meta?.definition[key]
+                ? { [key]: value }
+                : undefined;
+    }
+    catch (e) {
+        return { refusal: e instanceof Error ? e.message : String(e) };
     }
-    return displaySlots;
+    // A lift answering nothing has not placed the value — a `colorBy` naming a
+    // scheme this display never had, a `renderer` holding none of the props it
+    // retired. That is the `unknownKeys` report, not a silent write of nothing.
+    if (!members || Object.keys(members).length === 0) {
+        return undefined;
+    }
+    const refusal = Object.entries(members)
+        .map(([name, member]) => slotValueRefusal(schema, name, member))
+        .find(reason => reason !== undefined);
+    return refusal === undefined ? { members } : { refusal };
 }
 /**
- * Pure: route each shorthand `displayDefaults: {...}` setting to the display
- * types that define it. A setting goes to every display type whose config schema
- * has that slot, so slot names disambiguate across displays on their own (e.g.
- * `color` → LinearVariantDisplay, `strokeColor` → ChordVariantDisplay). Keys no
- * display defines are returned as `unknownKeys` for the caller to surface.
+ * Route each shorthand `displayDefaults: {...}` setting to the display types
+ * whose member of that name takes its value: `color: 'red'` reaches every
+ * display with a colour, `color: { field: 'type' }` only those whose colour
+ * maps a field, and a spelling a display retired reaches that display as the
+ * members it became. `reached` names the displays each key went to. A key no
+ * display knows is an `unknownKeys` entry, and one every display that knows it
+ * refuses a `refused` entry carrying each reason.
  */
-export function collectDisplayOverrides(displaySettings, displaySlots) {
+export function collectDisplayOverrides(displaySettings, displaySchemas) {
     const overrides = new Map();
+    const reached = new Map();
     const unknownKeys = [];
+    const refused = [];
     for (const [key, value] of Object.entries(displaySettings)) {
-        const targets = [...displaySlots]
-            .filter(([, slots]) => slots.has(key))
-            .map(([name]) => name);
-        if (targets.length) {
-            for (const name of targets) {
-                overrides.set(name, { ...overrides.get(name), [key]: value });
-            }
-        }
-        else {
+        const verdicts = [...displaySchemas].flatMap(([name, schema]) => {
+            const verdict = verdictOf(schema, key, value);
+            return verdict ? [{ name, ...verdict }] : [];
+        });
+        const targets = verdicts.filter(v => v.members);
+        if (verdicts.length === 0) {
             unknownKeys.push(key);
         }
+        else if (targets.length === 0) {
+            refused.push({
+                key,
+                reasons: verdicts.map(v => `${v.name}: ${v.refusal}`),
+            });
+        }
+        for (const { name, members } of targets) {
+            overrides.set(name, { ...overrides.get(name), ...members });
+        }
+        reached.set(key, targets.map(t => t.name));
     }
-    return { overrides, unknownKeys };
+    return { overrides, reached, unknownKeys, refused };
 }
 /**
- * Pure: fold per-display override props into a `displays` array, creating an
- * entry (with a derived displayId) for any display type not already present.
- * Explicit entries in the existing array win over shorthand on conflict.
+ * Fold per-display override props into the entries a `displays` array already
+ * has; explicit props win. A display with no entry gets none: a setting never
+ * adds a display to a track.
  */
-export function mergeOverridesIntoDisplays(displays, overrides, trackId) {
-    const seen = new Set();
-    const merged = displays.map(d => {
-        seen.add(d.type);
-        return { ...overrides.get(d.type), ...d };
-    });
-    for (const [name, props] of overrides) {
-        if (!seen.has(name)) {
-            merged.push({ type: name, displayId: `${trackId}-${name}`, ...props });
-        }
-    }
-    return merged;
+export function mergeOverridesIntoDisplays(displays, overrides) {
+    return displays.map(d => ({ ...overrides.get(d.type), ...d }));
 }
 /**
  * Expands the shorthand `displayDefaults` **object** into the explicit `displays`
  * **array**, so users can set display settings without naming the display type
  * or nesting in `displays:[{type,...}]`. `displayDefaults:{color:'green'}` routes
- * each setting to the display type(s) that define that slot, folding them into
- * whatever `displays` array the track already has (explicit entries win).
+ * each setting to the display type(s) whose slot takes it, folding them into
+ * the entries the `displays` array has (explicit props win). A key whose every
+ * taker is missing from the array, a display the track's adapter cannot feed,
+ * is reported rather than giving the track that display.
  *
  * `displayDefaults` is kept separate from `displays` (rather than overloading
  * `displays` by shape) so a config using it still loads in a JBrowse version
  * that predates the feature — the unknown key is ignored, instead of crashing
  * when the array-typed `displays` slot receives an object.
  *
- * Runs inside `baseTrackConfig.preProcessSnapshot`, before display-stub
+ * Runs inside `baseTrackConfig.preProcessSnapshot`, after display-stub
  * injection. Takes/returns the loosely-typed snapshot (as `evaluateExtensionPoint`
  * does) — the caller casts the result to its snapshot type for validation.
  */
@@ -101,15 +122,26 @@ export function expandTrackConfigShorthand(input, pluginManager) {
     if (!trackType.displayTypes.length) {
         return snap;
     }
-    const { overrides, unknownKeys } = collectDisplayOverrides(shorthand, trackDisplaySlots(trackType));
+    const { overrides, reached, unknownKeys, refused } = collectDisplayOverrides(shorthand, new Map(trackType.displayTypes.map(d => [d.name, d.configSchema])));
     for (const key of unknownKeys) {
         console.warn(`Track "${trackId}": display setting "${key}" is not a slot on any display of a ${type}`);
     }
+    if (refused.length > 0) {
+        throw new Error(refused
+            .map(({ key, reasons }) => `Track "${trackId}": no display of a ${type} takes displayDefaults.${key} (${reasons.join('; ')})`)
+            .join('\n'));
+    }
     const displays = Array.isArray(rest.displays)
         ? rest.displays
         : [];
+    const listed = new Set(displays.map(d => d.type));
+    for (const [key, names] of reached) {
+        if (names.length > 0 && !names.some(name => listed.has(name))) {
+            console.warn(`Track "${trackId}": displayDefaults.${key} reaches only ${names.join(', ')}, which its adapter cannot feed`);
+        }
+    }
     return {
         ...rest,
-        displays: mergeOverridesIntoDisplays(displays, overrides, trackId),
+        displays: mergeOverridesIntoDisplays(displays, overrides),
     };
 }

package/esm/pluggableElementTypes/models/index.d.ts

@@ -2,7 +2,6 @@ export { default as baseConnectionConfig } from './baseConnectionConfig.ts';
 export { default as BaseConnectionModelFactory } from './BaseConnectionModelFactory.ts';
 export { default as BaseViewModel } from './BaseViewModel.ts';
 export type { IBaseViewModel } from './BaseViewModel.ts';
-export { default as HighlightsMixin } from './HighlightsMixin.ts';
 export { BaseDisplay } from './BaseDisplayModel.tsx';
 export type { BaseDisplayModel, BaseDisplayStateModel, DisplayModel, } from './BaseDisplayModel.tsx';
 export { InternetAccount } from './InternetAccountModel.ts';
@@ -10,8 +9,8 @@ export type { BaseInternetAccountModel, BaseInternetAccountStateModel, } from '.
 export { BaseInternetAccountConfig } from './baseInternetAccountConfig.ts';
 export { createBaseTrackModel } from './BaseTrackModel.ts';
 export type { BaseTrackModel, BaseTrackStateModel } from './BaseTrackModel.ts';
-export { createBaseTrackConfig, preprocessTrackConfigSnapshot, trackConfigActions, } from './baseTrackConfig.ts';
+export { createBaseTrackConfig, preprocessTrackConfigSnapshot, } from './baseTrackConfig.ts';
 export type { BaseTrackConfig } from './baseTrackConfig.ts';
-export { addDisplayConfigMigration } from './migrateTrackConfig.ts';
+export { migrateRetiredDisplays } from './migrateTrackConfig.ts';
 export type { TrackConfigSnapshot } from './migrateTrackConfig.ts';
 export type { FileTypeExporter } from './saveTrackFileTypes/types.ts';

package/esm/pluggableElementTypes/models/index.js

@@ -1,10 +1,9 @@
 export { default as baseConnectionConfig } from './baseConnectionConfig.js';
 export { default as BaseConnectionModelFactory } from './BaseConnectionModelFactory.js';
 export { default as BaseViewModel } from './BaseViewModel.js';
-export { default as HighlightsMixin } from './HighlightsMixin.js';
 export { BaseDisplay } from './BaseDisplayModel.js';
 export { InternetAccount } from './InternetAccountModel.js';
 export { BaseInternetAccountConfig } from './baseInternetAccountConfig.js';
 export { createBaseTrackModel } from './BaseTrackModel.js';
-export { createBaseTrackConfig, preprocessTrackConfigSnapshot, trackConfigActions, } from './baseTrackConfig.js';
-export { addDisplayConfigMigration } from './migrateTrackConfig.js';
+export { createBaseTrackConfig, preprocessTrackConfigSnapshot, } from './baseTrackConfig.js';
+export { migrateRetiredDisplays } from './migrateTrackConfig.js';

package/esm/pluggableElementTypes/models/migrateTrackConfig.d.ts

@@ -15,7 +15,21 @@ declare module '../../PluginManager.ts' {
         };
     }
 }
-export declare function addDisplayConfigMigration(pluginManager: PluginManager, displayTypes: string[], migrate: (displaySnap: Record<string, unknown>) => Record<string, unknown>): void;
+/**
+ * Loads each display entry a retired type names as the display it retired
+ * into, and rewrites every entry's retired spellings, as each DisplayType's
+ * `retiredTypes` and its config schema's `retired` declare. Runs on the track
+ * config before the `Core-preProcessTrackConfig` handlers, which read the
+ * current names, and before the display union, which refuses a retired value
+ * where a schema's own `preProcessSnapshot` never runs.
+ *
+ * Entries that collapse onto one type become one: an entry written for this
+ * display beats one written for a retired type, a bare `{ type, displayId }`
+ * stub yields to either, and among equals the first wins. The survivor takes
+ * the first one's place and id, so the default display and the references a
+ * session holds stay where they were.
+ */
+export declare function migrateRetiredDisplays(pluginManager: PluginManager, snap: TrackConfigSnapshot): TrackConfigSnapshot;
 export interface LegacyDisplaySnapshot {
     type: string;
     displayId?: string;

package/esm/pluggableElementTypes/models/migrateTrackConfig.js

@@ -1,33 +1,93 @@
 // Back-compat migration for track config snapshots. Kept out of
 // baseTrackConfig.ts so the schema definition stays free of legacy-format
 // handling.
+import { getConfigurationSchemaMetadata } from '../../configuration/schemaRegistry.js';
+import { liftRetiredSpellings } from '../../configuration/snapshotPreprocess.js';
 // #endregion
-// Registers a back-compat migration for a display's CONFIG snapshot that runs
-// BEFORE the display `types.union` validates it.
-//
-// Use this — NOT a config-schema `preProcessSnapshot` — whenever the migration
-// rewrites the VALUE of an existing constrained slot (enum rename, type narrow).
-// A config-schema `preProcessSnapshot` does not run during union validation
-// (the union tests the raw snapshot), so the union rejects the legacy value
-// first and the migration never fires. A slot add/remove/rename, where the old
-// data becomes an unknown extra prop, does NOT need this — the union ignores
-// unknown props, so a config-schema `preProcessSnapshot` is fine there.
-//
-// Pass every type name the display answers to (canonical + aliases); this runs
-// before alias normalization. `migrate` must be idempotent (it also fires via
-// the config-schema `preProcessSnapshot` on a direct create).
-export function addDisplayConfigMigration(pluginManager, displayTypes, migrate) {
-    const match = new Set(displayTypes);
-    const matches = (d) => typeof d.type === 'string' && match.has(d.type);
-    pluginManager.addToExtensionPoint('Core-preProcessTrackConfig', snap => {
-        const { displays } = snap;
-        return Array.isArray(displays) && displays.some(matches)
-            ? {
-                ...snap,
-                displays: displays.map(d => (matches(d) ? migrate(d) : d)),
-            }
-            : snap;
+const isBareEntry = (entry) => Object.keys(entry).every(k => k === 'type' || k === 'displayId');
+/**
+ * Loads each display entry a retired type names as the display it retired
+ * into, and rewrites every entry's retired spellings, as each DisplayType's
+ * `retiredTypes` and its config schema's `retired` declare. Runs on the track
+ * config before the `Core-preProcessTrackConfig` handlers, which read the
+ * current names, and before the display union, which refuses a retired value
+ * where a schema's own `preProcessSnapshot` never runs.
+ *
+ * Entries that collapse onto one type become one: an entry written for this
+ * display beats one written for a retired type, a bare `{ type, displayId }`
+ * stub yields to either, and among equals the first wins. The survivor takes
+ * the first one's place and id, so the default display and the references a
+ * session holds stay where they were.
+ */
+export function migrateRetiredDisplays(pluginManager, snap) {
+    const { displays, trackId } = snap;
+    if (!Array.isArray(displays) || displays.length === 0) {
+        return snap;
+    }
+    const elements = pluginManager.getDisplayElements();
+    const byName = new Map(elements.map(d => [d.name, d]));
+    const byRetiredName = new Map(elements.flatMap(d => d.retiredTypes.map(r => [r.type, { d, r }])));
+    const migrated = displays.map((entry) => {
+        const type = entry.type;
+        const retired = type === undefined ? undefined : byRetiredName.get(type);
+        const display = retired?.d ?? (type ? byName.get(type) : undefined);
+        if (!display) {
+            return { entry, rank: 0 };
+        }
+        let next = entry;
+        if (retired) {
+            const { displayId } = entry;
+            next = {
+                ...(retired.r.migrate?.(entry) ?? entry),
+                type: display.name,
+                ...(displayId === undefined
+                    ? {}
+                    : {
+                        displayId: displayId === `${String(trackId)}-${type}`
+                            ? `${String(trackId)}-${display.name}`
+                            : displayId,
+                    }),
+            };
+        }
+        const meta = getConfigurationSchemaMetadata(display.configSchema);
+        next = meta ? liftRetiredSpellings(meta, next) : next;
+        return {
+            entry: next,
+            type: display.name,
+            rank: isBareEntry(entry) ? 1 : retired ? 2 : 3,
+        };
     });
+    if (migrated.every((m, i) => m.entry === displays[i] && m.type === displays[i].type) &&
+        new Set(migrated.map(m => m.type)).size === migrated.length) {
+        return snap;
+    }
+    const winners = new Map();
+    for (const m of migrated) {
+        const best = m.type === undefined ? undefined : winners.get(m.type);
+        if (m.type !== undefined && (!best || m.rank > best.rank)) {
+            winners.set(m.type, m);
+        }
+    }
+    const placed = new Set();
+    return {
+        ...snap,
+        displays: migrated.flatMap(m => {
+            if (m.type === undefined) {
+                return [m.entry];
+            }
+            if (placed.has(m.type)) {
+                return [];
+            }
+            placed.add(m.type);
+            const winner = winners.get(m.type);
+            const displayId = m.entry.displayId ?? winner.entry.displayId;
+            return [
+                winner === m || displayId === undefined
+                    ? winner.entry
+                    : { ...winner.entry, displayId },
+            ];
+        }),
+    };
 }
 // The GPU rewrite removed the per-display `renderer` sub-config (which carried
 // color/height/etc.). Old configs still nest those values under `renderer`, so

package/esm/pluggableElementTypes/models/saveTrackFileTypes/genbank.d.ts

@@ -1,13 +1,14 @@
-import type { AbstractSessionModel, Feature, StatusCallback, StopToken } from '../../../util/index.ts';
+import type { AbstractSessionModel, Feature, StatusCallback } from '../../../util/index.ts';
+export declare function insdcFeatureKey(type: string): string;
 export declare function formatFeatWithSubfeatures({ feature, minPos, geneName, }: {
     feature: Feature;
     minPos: number;
     geneName?: string;
 }): string;
-export declare function stringifyGBK({ features, assemblyName, session, stopToken, statusCallback, }: {
+export declare function stringifyGBK({ features, assemblyName, session, signal, statusCallback, }: {
     assemblyName: string;
     session: AbstractSessionModel;
     features: Feature[];
-    stopToken?: StopToken;
+    signal?: AbortSignal;
     statusCallback?: StatusCallback;
 }): Promise<string>;