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

package/esm/configuration/indexType.d.ts

@@ -0,0 +1,26 @@
+/** The sibling index format of a family: TBI for tabix, BAI for BAM. */
+export type SiblingIndexType = 'TBI' | 'BAI';
+export type IndexType = SiblingIndexType | 'CSI';
+/** The extension an index of this type carries: `CSI` → `.csi`, `TBI` → `.tbi`. */
+export declare function indexSuffix(indexType: IndexType): string;
+/**
+ * Whether a file location names a CSI. htslib writes `.csi` in place of a `.bai`
+ * or a `.tbi` for a reference over 512 Mb and on request at any size, so the
+ * extension is the only thing distinguishing the two parsers.
+ *
+ * `makeIndexType` in `util/tracks.ts` asks this of a bare filename, for the
+ * guessers and add-track forms that WRITE an `indexType` beside the location.
+ * Those stay: a config the CLI or jbrowse-img writes is read by older JBrowse
+ * versions, which have no inference to fall back on.
+ */
+export declare function isCsiLocation(location: unknown): boolean;
+/**
+ * An index sub-schema's snapshot with `indexType` filled in from the location it
+ * names, where it states none. Only CSI is ever filled in — the sibling format
+ * is the slot's own default.
+ *
+ * Belongs to the sub-schema rather than to the `uri` shorthand because it has to
+ * cover the paths no shorthand runs on: a long-form config, and an add-track
+ * form that writes a location and nothing else.
+ */
+export declare function fillIndexType(snap: Record<string, unknown>): Record<string, unknown>;

package/esm/configuration/indexType.js

@@ -0,0 +1,38 @@
+import { isPlainObject } from '../util/objectUtils.js';
+/** The extension an index of this type carries: `CSI` → `.csi`, `TBI` → `.tbi`. */
+export function indexSuffix(indexType) {
+    return `.${indexType.toLowerCase()}`;
+}
+/**
+ * Whether a file location names a CSI. htslib writes `.csi` in place of a `.bai`
+ * or a `.tbi` for a reference over 512 Mb and on request at any size, so the
+ * extension is the only thing distinguishing the two parsers.
+ *
+ * `makeIndexType` in `util/tracks.ts` asks this of a bare filename, for the
+ * guessers and add-track forms that WRITE an `indexType` beside the location.
+ * Those stay: a config the CLI or jbrowse-img writes is read by older JBrowse
+ * versions, which have no inference to fall back on.
+ */
+export function isCsiLocation(location) {
+    if (!isPlainObject(location)) {
+        return false;
+    }
+    const { uri, localPath } = location;
+    const name = typeof uri === 'string' ? uri : localPath;
+    // a presigned url carries its query string after the name
+    return typeof name === 'string' && /\.csi$/i.test(name.split(/[?#]/)[0]);
+}
+/**
+ * An index sub-schema's snapshot with `indexType` filled in from the location it
+ * names, where it states none. Only CSI is ever filled in — the sibling format
+ * is the slot's own default.
+ *
+ * Belongs to the sub-schema rather than to the `uri` shorthand because it has to
+ * cover the paths no shorthand runs on: a long-form config, and an add-track
+ * form that writes a location and nothing else.
+ */
+export function fillIndexType(snap) {
+    return snap.indexType === undefined && isCsiLocation(snap.location)
+        ? { ...snap, indexType: 'CSI' }
+        : snap;
+}

package/esm/configuration/mergeFormatCallbacks.d.ts

@@ -4,12 +4,11 @@
  * first, so a track's object is spread over the session-wide one and can
  * override individual keys the global callback added.
  *
- * A tier that isn't a plain object is dropped rather than spread. The classic
- * slip is `"jexl:feature.name"` where `"jexl:{name:feature.name}"` was meant;
- * spreading the resulting string produced attribute rows keyed `0`, `1`, `2`,
- * and an array does the same, which is why `isObject` alone isn't the gate.
- *
- * `null` and `undefined` *values* survive on purpose: they are how a callback
- * hides a field, and the panels filter them out downstream.
+ * A tier that returns something other than an object is an authoring mistake,
+ * `"jexl:feature.name"` where `"jexl:{name:feature.name}"` was meant, and it
+ * throws rather than vanishing: spread, the string became rows keyed 0, 1, 2,
+ * and dropped, the author's callback silently did nothing. A tier returning
+ * null or undefined has nothing to add. `null` and `undefined` *values* survive:
+ * they are how a callback hides a field, and the panels filter them downstream.
  */
 export declare function mergeFormatCallbacks(...tiers: unknown[]): Record<string, unknown>;

package/esm/configuration/mergeFormatCallbacks.js

@@ -1,24 +1,27 @@
-import { isObject } from '../util/objectUtils.js';
+import { isPlainObject } from '../util/objectUtils.js';
 /**
  * Combine the tiers of an object-returning format callback (`formatDetails` on
  * the feature-details panel, `formatAbout` on the About dialog), earliest
  * first, so a track's object is spread over the session-wide one and can
  * override individual keys the global callback added.
  *
- * A tier that isn't a plain object is dropped rather than spread. The classic
- * slip is `"jexl:feature.name"` where `"jexl:{name:feature.name}"` was meant;
- * spreading the resulting string produced attribute rows keyed `0`, `1`, `2`,
- * and an array does the same, which is why `isObject` alone isn't the gate.
- *
- * `null` and `undefined` *values* survive on purpose: they are how a callback
- * hides a field, and the panels filter them out downstream.
+ * A tier that returns something other than an object is an authoring mistake,
+ * `"jexl:feature.name"` where `"jexl:{name:feature.name}"` was meant, and it
+ * throws rather than vanishing: spread, the string became rows keyed 0, 1, 2,
+ * and dropped, the author's callback silently did nothing. A tier returning
+ * null or undefined has nothing to add. `null` and `undefined` *values* survive:
+ * they are how a callback hides a field, and the panels filter them downstream.
  */
 export function mergeFormatCallbacks(...tiers) {
     const out = {};
     for (const tier of tiers) {
-        if (isObject(tier) && !Array.isArray(tier)) {
-            Object.assign(out, tier);
+        if (tier == null) {
+            continue;
+        }
+        if (!isPlainObject(tier)) {
+            throw new Error(`a format callback returned ${Array.isArray(tier) ? 'an array' : `a ${typeof tier}`} where an object of fields was expected, e.g. "jexl:{name:feature.name}" rather than "jexl:feature.name"`);
         }
+        Object.assign(out, tier);
     }
     return out;
 }

package/esm/configuration/readConfObject.d.ts

@@ -1,7 +1,6 @@
 import type { Feature } from '../util/index.ts';
 import type { JexlInstance } from '../util/jexlStrings.ts';
-import type { AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValue } from './types.ts';
-import type { IMSTMap } from '@jbrowse/mobx-state-tree';
+import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue } from './types.ts';
 /**
  * #api core/configuration
  * Given a configuration model (an instance of a ConfigurationSchema), read the
@@ -25,8 +24,7 @@ import type { IMSTMap } from '@jbrowse/mobx-state-tree';
  *  will be sent to each of the slotNames
  */
 export declare function readConfObject(confObject: AnyConfigurationModel): AnyConfigurationSnapshot;
-export declare function readConfObject<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | string[] = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(confObject: CONFMODEL, slotPath?: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : any;
-export declare function readConfObject(confObject: IMSTMap<AnyConfigurationSchemaType>, slotPath?: string | string[], args?: Record<string, unknown>): any;
+export declare function readConfObject<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(confObject: CONFMODEL, slotPath?: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : ConfigurationSlotPathValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT>;
 /**
  * Read a value from a plain config snapshot object. Automatically evaluates
  * "jexl:..." strings per-feature. Works without MST — intended for use in
@@ -34,23 +32,3 @@ export declare function readConfObject(confObject: IMSTMap<AnyConfigurationSchem
  * so plugin-registered functions (e.g. in a custom `mouseover` slot) resolve.
  */
 export declare function readConfigValue<T>(config: Record<string, unknown>, key: string | string[], feature: Feature, jexl: JexlInstance): T;
-/**
- * #api core/configuration
- * Read a single config slot from a config that may be **either** a live MST
- * node or a plain snapshot object, evaluating the value if it is a `jexl:`
- * expression. For the dialogs and panels that are handed a track config without
- * knowing which of the two they got. An About panel gets a hydrated track
- * config from the session and a bare object from an embedded caller.
- *
- * Reach for `readConfObject` or `readConfigValue` when the shape is known:
- * this one decides at runtime, and the plain branch inherits the snapshot
- * caveat (a slot at its default is absent from a snapshot, so it reads
- * `undefined`).
- *
- * @param config - live config model or plain config object
- * @param slotPath - slot name, or path of sub-config names ending in a slot
- * @param args - extra arguments for a callback slot, e.g. `{ feature }`
- * @param jexl - realm jexl instance, required only to evaluate a callback slot
- *  on a plain object (a live node resolves its own from env)
- */
-export declare function readConfSlot<T = unknown>(config: AnyConfigurationModel | Record<string, unknown>, slotPath: string | string[], args?: Record<string, unknown>, jexl?: JexlInstance): T;

package/esm/configuration/readConfObject.js

@@ -1,13 +1,14 @@
 /**
  * @module
- * The config **readers**: `readConfObject` off a live MST config node,
- * `readConfigValue` off a plain snapshot object in a worker or a renderer, and
- * `readConfSlot` for the callers that hold either and don't know which. All
- * three exist to evaluate a slot's `jexl:...` callback on read; they differ only
- * in where the jexl instance comes from (the node's env vs. an explicit
- * argument) and in how much of that they are willing to decide at runtime.
+ * The config **readers**: `readConfObject` off a live MST config node, and
+ * `readConfigValue` off a plain snapshot object in a worker or a renderer. Both
+ * exist to evaluate a slot's `jexl:...` callback on read; they differ only in
+ * where the jexl instance comes from, the node's env or an explicit argument.
+ * A `featureField` slot's `jexl:` expression is the display's to evaluate per
+ * feature, so `readConfObject` hands it over as written.
  */
-import { getEnv, getSnapshot, getType, isMapType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+import { getEnv, getSnapshot, getType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
 import { evaluateJexl, isCallbackValue } from './slotValueUtils.js';
 // Evaluate a slot's `jexl:...` callback string against the realm's single jexl
 // instance (carrying plugin-registered functions), read from the config node's
@@ -30,26 +31,20 @@ function evalConfigCallback(expr, args, confObject) {
     }
     return evaluateJexl(expr, args, jexl);
 }
-function isConfigMap(confObject) {
-    return isStateTreeNode(confObject) && isMapType(getType(confObject));
-}
-// Read a slot's raw stored value, drilling into a map entry via `.get()` when
-// the config is itself a types.map.
-function rawSlotValue(confObject, slotName) {
-    return isConfigMap(confObject)
-        ? confObject.get(slotName)
-        : confObject[slotName];
+function isFeatureField(confObject, slotName) {
+    return (isStateTreeNode(confObject) &&
+        !!getConfigurationSchemaMetadata(getType(confObject))?.featureFields.has(slotName));
 }
 // Read and resolve a single slot: raw value, jexl callback evaluation, then a
 // referentially-stable snapshot for sub-config nodes.
 function readSlot(confObject, slotName, args) {
     // strict undefined check, not truthiness — a slot value can legitimately be
     // falsy (0, '', false, null)
-    const value = rawSlotValue(confObject, slotName);
+    const value = confObject[slotName];
     if (value === undefined) {
         return undefined;
     }
-    const val = isCallbackValue(value)
+    const val = isCallbackValue(value) && !isFeatureField(confObject, slotName)
         ? evalConfigCallback(value, args, confObject)
         : value;
     // Fast path for primitives (most common case)
@@ -63,8 +58,9 @@ function readSlot(confObject, slotName, args) {
     return isStateTreeNode(val) ? getSnapshot(val) : val;
 }
 // loose implementation signature: the body returns values that are `any` by
-// nature (raw slot values, snapshots); the typed overload above is what callers
-// see.
+// nature (raw slot values, snapshots); the typed overloads above are what
+// callers see. No looser overload admits the model: one that did was a
+// catch-all a slot-name typo fell through to, compiling clean as `any`.
 export function readConfObject(confObject, slotPath, args = {}) {
     // the single-slot read, first and allocation-free: it is the shape of nearly
     // every one of the ~1300 call sites, so it doesn't get normalized into a
@@ -89,7 +85,7 @@ export function readConfObject(confObject, slotPath, args = {}) {
     // whole argument-shape preamble above at each level.
     let conf = confObject;
     for (let i = 0; i < slotPath.length - 1; i++) {
-        const subConf = rawSlotValue(conf, slotPath[i]);
+        const subConf = conf[slotPath[i]];
         if (subConf === undefined) {
             return undefined;
         }
@@ -97,10 +93,9 @@ export function readConfObject(confObject, slotPath, args = {}) {
     }
     return readSlot(conf, slotPath[slotPath.length - 1], args);
 }
-// The plain-object half of the slot walk, shared by readConfigValue and
-// readConfSlot. The MST half is readSlot/rawSlotValue above. A plain object has
-// no map entries and no sub-config nodes to snapshot, so it is just a path
-// reduce.
+// The plain-object half of the slot walk, for readConfigValue. The MST half is
+// readSlot/rawSlotValue above. A plain object has no map entries and no
+// sub-config nodes to snapshot, so it is just a path reduce.
 function resolveConfigValue(config, key) {
     if (Array.isArray(key)) {
         let val = config;
@@ -121,41 +116,3 @@ export function readConfigValue(config, key, feature, jexl) {
     const raw = resolveConfigValue(config, key);
     return (isCallbackValue(raw) ? evaluateJexl(raw, { feature }, jexl) : raw);
 }
-/**
- * #api core/configuration
- * Read a single config slot from a config that may be **either** a live MST
- * node or a plain snapshot object, evaluating the value if it is a `jexl:`
- * expression. For the dialogs and panels that are handed a track config without
- * knowing which of the two they got. An About panel gets a hydrated track
- * config from the session and a bare object from an embedded caller.
- *
- * Reach for `readConfObject` or `readConfigValue` when the shape is known:
- * this one decides at runtime, and the plain branch inherits the snapshot
- * caveat (a slot at its default is absent from a snapshot, so it reads
- * `undefined`).
- *
- * @param config - live config model or plain config object
- * @param slotPath - slot name, or path of sub-config names ending in a slot
- * @param args - extra arguments for a callback slot, e.g. `{ feature }`
- * @param jexl - realm jexl instance, required only to evaluate a callback slot
- *  on a plain object (a live node resolves its own from env)
- */
-export function readConfSlot(config, slotPath, args = {}, jexl) {
-    if (isStateTreeNode(config)) {
-        // pass slotPath through rather than normalizing a string into a one-element
-        // array: readConfObject keeps the single-slot read allocation-free
-        return readConfObject(config, slotPath, args);
-    }
-    const value = resolveConfigValue(config, slotPath);
-    // A plain-object config has no MST env, so the realm's jexl instance can't be
-    // resolved automatically — callers reading a callback slot must pass it. Only
-    // reached when the slot actually holds a `jexl:` value (trackId/adapter/etc.
-    // never do), so non-callback readers need not supply it.
-    if (isCallbackValue(value)) {
-        if (!jexl) {
-            throw new Error(`cannot evaluate jexl config slot ${JSON.stringify(slotPath)} on a plain-object config: no jexl instance provided`);
-        }
-        return evaluateJexl(value, args, jexl);
-    }
-    return value;
-}

package/esm/configuration/requirements.d.ts

@@ -0,0 +1,37 @@
+import type { ConfigurationSchemaDefinition } from './configurationSchema.ts';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
+/**
+ * A combination one config object cannot mean, declared once: when every slot
+ * named in `when` holds one of the listed values, each dotted path in `slots`
+ * has to name a value — a non-empty string, or a sub-schema a string lifts
+ * into. `message` says why, and `id` is the stable name a report carries.
+ * `requirementProblems` reads it for a display's notice, and the generated
+ * JSON Schema carries it as `if`/`then` with the message, which the CLI
+ * validator and an editor report.
+ *
+ * `ConfigurationSchema()` types `when`, its values and `slots` off the
+ * definition and throws at construction for what the types cannot reach: a
+ * misspelt `when` key or value would never fire, and a misspelt path would
+ * require a key `closed` then refuses.
+ */
+export interface ConfigurationSchemaRequirement<WHEN extends Partial<Record<string, string[]>> = Partial<Record<string, string[]>>, PATH extends string = string> {
+    id: string;
+    when: WHEN;
+    slots: PATH[];
+    message: string;
+}
+/** A requirement a snapshot does not meet: the slot path left empty, and why. */
+export interface RequirementProblem {
+    id: string;
+    slot: string;
+    message: string;
+}
+export declare function checkRequirements(modelName: string, definition: ConfigurationSchemaDefinition, requires: ConfigurationSchemaRequirement[]): void;
+/**
+ * #api core/configuration
+ * The `requires` entries of a configuration schema that `snapshot` does not
+ * meet, as a config file or `getSnapshot` spells it: a slot left off reads as
+ * its default, so a `when` value that is the default fires for an absent slot,
+ * which is what the generated JSON Schema's `if` does.
+ */
+export declare function requirementProblems(type: IAnyType, snapshot: Record<string, unknown>): RequirementProblem[];

package/esm/configuration/requirements.js

@@ -0,0 +1,88 @@
+import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
+import { isBareConfigurationSchemaType, isSlotDefinitionEntry, shorthandTargets, } from './schemaTypes.js';
+function memberOf(definition, name) {
+    return Object.hasOwn(definition, name) ? definition[name] : undefined;
+}
+function subSchemaOf(entry) {
+    return isBareConfigurationSchemaType(entry)
+        ? getConfigurationSchemaMetadata(entry)
+        : undefined;
+}
+function requiredPathProblem(modelName, definition, path) {
+    const [head = '', ...rest] = path;
+    const entry = memberOf(definition, head);
+    const sub = subSchemaOf(entry);
+    return entry === undefined
+        ? `${modelName} declares no "${head}"`
+        : rest.length > 0
+            ? sub
+                ? requiredPathProblem(sub.name, sub.definition, rest)
+                : `"${head}" is not a single sub-schema, so no path runs through it`
+            : isSlotDefinitionEntry(entry)
+                ? entry.defaultValue === undefined ||
+                    typeof entry.defaultValue === 'string'
+                    ? undefined
+                    : `"${head}" holds no string, and a requirement is met by naming one`
+                : sub?.options.shorthand !== undefined
+                    ? undefined
+                    : `"${head}" is neither a slot nor a sub-schema a string lifts into`;
+}
+export function checkRequirements(modelName, definition, requires) {
+    for (const { when, slots } of requires) {
+        for (const [slot, values = []] of Object.entries(when)) {
+            const entry = memberOf(definition, slot);
+            if (!isSlotDefinitionEntry(entry)) {
+                throw new Error(`${modelName} requires something when "${slot}" holds a value, and declares no such slot`);
+            }
+            const refused = values.filter(value => entry.model?.is(value) === false);
+            if (refused.length > 0) {
+                throw new Error(`${modelName} requires something when "${slot}" holds ${refused.join(', ')}, which the slot does not take`);
+            }
+        }
+        for (const path of slots) {
+            const problem = requiredPathProblem(modelName, definition, path.split('.'));
+            if (problem) {
+                throw new Error(`${modelName} requires "${path}", and ${problem}`);
+            }
+        }
+    }
+}
+function namesAValue(definition, snapshot, path) {
+    const [head = '', ...rest] = path;
+    const value = typeof snapshot === 'object' && snapshot !== null
+        ? snapshot[head]
+        : undefined;
+    const sub = subSchemaOf(memberOf(definition, head));
+    const named = sub && shorthandTargets(sub).string;
+    return rest.length > 0
+        ? sub !== undefined && namesAValue(sub.definition, value, rest)
+        : typeof value === 'string'
+            ? value !== ''
+            : sub !== undefined &&
+                named !== undefined &&
+                namesAValue(sub.definition, value, [named]);
+}
+/**
+ * #api core/configuration
+ * The `requires` entries of a configuration schema that `snapshot` does not
+ * meet, as a config file or `getSnapshot` spells it: a slot left off reads as
+ * its default, so a `when` value that is the default fires for an absent slot,
+ * which is what the generated JSON Schema's `if` does.
+ */
+export function requirementProblems(type, snapshot) {
+    const schema = getConfigurationSchemaMetadata(type);
+    if (!schema) {
+        return [];
+    }
+    const { definition } = schema;
+    return (schema.options.requires ?? [])
+        .filter(({ when }) => Object.entries(when).every(([slot, values]) => {
+        const entry = memberOf(definition, slot);
+        const held = snapshot[slot] ??
+            (isSlotDefinitionEntry(entry) ? entry.defaultValue : undefined);
+        return typeof held === 'string' && values?.includes(held);
+    }))
+        .flatMap(({ id, slots, message }) => slots
+        .filter(path => !namesAValue(definition, snapshot, path.split('.')))
+        .map(slot => ({ id, slot, message })));
+}

package/esm/configuration/schemaRegistry.d.ts

@@ -1,7 +1,9 @@
 import type { ConfigurationSchemaDefinition, MergedConfigurationSchemaOptions } from './configurationSchema.ts';
-import type { AnyConfigurationModel } from './types.ts';
+import type { AnyConfigurationModel, AnyConfigurationSchemaType } from './types.ts';
 import type { IAnyType } from '@jbrowse/mobx-state-tree';
 export interface ConfigurationSchemaMetadata {
+    /** the name `ConfigurationSchema` was given, e.g. `FeatureColor` */
+    name: string;
     /** the raw slot/sub-schema/constant table, also carrying per-slot editor metadata */
     definition: ConfigurationSchemaDefinition;
     /**
@@ -9,27 +11,42 @@ export interface ConfigurationSchemaMetadata {
      * i.e. with any `baseConfiguration`'s hooks already composed in
      */
     options: MergedConfigurationSchemaOptions<any, any>;
+    /** the frozen-family slots, the only members a snapshot's `null` is stored in */
+    storesNull: ReadonlySet<string>;
+    /** the `featureField` slots, which the reader hands over as written */
+    featureFields: ReadonlySet<string>;
+    /** the slots that refuse a `jexl:` string: every one but a callback and a featureField */
+    takesNoCallback: ReadonlyMap<string, string>;
 }
 export declare function registerConfigurationSchema(type: IAnyType, metadata: ConfigurationSchemaMetadata): void;
-export declare function getConfigurationSchemaMetadata(type: IAnyType): ConfigurationSchemaMetadata | undefined;
+/**
+ * A schema's metadata, by the schema type or a live node of it. Undefined for
+ * anything `ConfigurationSchema` did not build — a pluggable union, an array
+ * of schemas.
+ */
+export declare function getConfigurationSchemaMetadata(nodeOrType: AnyConfigurationModel | IAnyType): ConfigurationSchemaMetadata | undefined;
 export declare function isRegisteredConfigurationSchema(type: IAnyType): boolean;
+export interface ConfigurationSchemaUnionMetadata {
+    /** the name `ConfigurationSchemaUnion` was given, e.g. `MarkTransform` */
+    name: string;
+    /** each member schema, keyed by the `type` it answers to */
+    members: Record<string, AnyConfigurationSchemaType>;
+}
+export declare function registerConfigurationSchemaUnion(type: IAnyType, metadata: ConfigurationSchemaUnionMetadata): void;
+/**
+ * The name and members of a union `ConfigurationSchemaUnion` built, or
+ * undefined for any other type — a pluggable element union included.
+ */
+export declare function getConfigurationSchemaUnion(type: IAnyType): ConfigurationSchemaUnionMetadata | undefined;
 /**
  * The slot/sub-schema/constant table for a config (includes slots merged in from
  * `baseConfiguration` at schema construction). Undefined when the argument isn't
  * a registered configuration schema. The single accessor for "what are this
- * config's slots?" — shared by the slot facade, promotable defaults, and
- * `fullConfSnapshot`.
+ * config's slots?" — shared by the slot facade and `fullConfSnapshot`.
  *
- * Takes a live node *or* the schema type itself. Every in-tree reader holds a
- * node, which is why the `getType` hop is here; a caller enumerating registered
- * element types (`ConfigSlotDefaults.test.ts`) holds only the type, and for a
- * track schema it cannot get a node — `explicitIdentifier` makes `trackId` a
- * required MST identifier, so there is nothing to `create({})`.
+ * Takes a live node *or* the schema type itself: a caller enumerating
+ * registered element types (`ConfigSlotDefaults.test.ts`) holds only the type,
+ * and for a track schema it cannot get a node — `explicitIdentifier` makes
+ * `trackId` a required MST identifier, so there is nothing to `create({})`.
  */
 export declare function getConfigurationSchemaDefinition(nodeOrType: AnyConfigurationModel | IAnyType): ConfigurationSchemaDefinition | undefined;
-/**
- * The construction options a live config node's schema was built with
- * (identifier kind, `explicitlyTyped`, the `preProcessSnapshot` hook). Undefined
- * when the node's type isn't a registered configuration schema.
- */
-export declare function getConfigurationSchemaOptions(node: AnyConfigurationModel): MergedConfigurationSchemaOptions<any, any> | undefined;

package/esm/configuration/schemaRegistry.js

@@ -1,50 +1,48 @@
-import { getType, isType } from '@jbrowse/mobx-state-tree';
-// Per-schema metadata keyed by the MST type itself. Registered for BOTH the
-// outer stripDefault wrapper (what `ConfigurationSchema` returns and what
-// sub-schema properties hold) and the inner model (what `getType(node)` returns
-// for a live config), so a lookup succeeds from either handle.
-//
-// This replaces stamping `jbrowseSchemaDefinition`/`jbrowseSchemaOptions`/
-// `isJBrowseConfigurationSchema` onto the MST type objects: the type stays a
-// plain MST type, "is this a config schema" is registry membership instead of a
-// flag-or-name-match, and the metadata is reached by type identity. The map is
-// weak, so a discarded schema type is collected normally.
+import { getType, isType, unwrapType } from '@jbrowse/mobx-state-tree';
+// Per-schema metadata keyed by the model type `ConfigurationSchema` builds. A
+// lookup arrives by any handle on it — the stripDefault wrapper the factory
+// returns and a sub-schema property holds, an `optional` or `snapshotProcessor`
+// around that, a resolved `types.late`, or `getType(node)` — and `unwrapType`
+// takes each to the model. The type stays a plain MST type, "is this a config
+// schema" is registry membership, and the map is weak, so a discarded schema
+// type is collected normally.
 const schemaRegistry = new WeakMap();
 export function registerConfigurationSchema(type, metadata) {
     schemaRegistry.set(type, metadata);
 }
-export function getConfigurationSchemaMetadata(type) {
-    return schemaRegistry.get(type);
+/**
+ * A schema's metadata, by the schema type or a live node of it. Undefined for
+ * anything `ConfigurationSchema` did not build — a pluggable union, an array
+ * of schemas.
+ */
+export function getConfigurationSchemaMetadata(nodeOrType) {
+    return schemaRegistry.get(unwrapType(isType(nodeOrType) ? nodeOrType : getType(nodeOrType)));
 }
 export function isRegisteredConfigurationSchema(type) {
-    return schemaRegistry.has(type);
+    return schemaRegistry.has(unwrapType(type));
+}
+const unionRegistry = new WeakMap();
+export function registerConfigurationSchemaUnion(type, metadata) {
+    unionRegistry.set(type, metadata);
+}
+/**
+ * The name and members of a union `ConfigurationSchemaUnion` built, or
+ * undefined for any other type — a pluggable element union included.
+ */
+export function getConfigurationSchemaUnion(type) {
+    return unionRegistry.get(type);
 }
-// The three lookups above take a schema *type*; the two below take a live config
-// *node* and make the `getType` hop themselves, which is what every reader
-// actually wants — a node is what they hold. Leaving the hop to the call site is
-// how `slotFacade` came to reach the registry directly for `options` while going
-// through a helper for `definition`.
 /**
  * The slot/sub-schema/constant table for a config (includes slots merged in from
  * `baseConfiguration` at schema construction). Undefined when the argument isn't
  * a registered configuration schema. The single accessor for "what are this
- * config's slots?" — shared by the slot facade, promotable defaults, and
- * `fullConfSnapshot`.
+ * config's slots?" — shared by the slot facade and `fullConfSnapshot`.
  *
- * Takes a live node *or* the schema type itself. Every in-tree reader holds a
- * node, which is why the `getType` hop is here; a caller enumerating registered
- * element types (`ConfigSlotDefaults.test.ts`) holds only the type, and for a
- * track schema it cannot get a node — `explicitIdentifier` makes `trackId` a
- * required MST identifier, so there is nothing to `create({})`.
+ * Takes a live node *or* the schema type itself: a caller enumerating
+ * registered element types (`ConfigSlotDefaults.test.ts`) holds only the type,
+ * and for a track schema it cannot get a node — `explicitIdentifier` makes
+ * `trackId` a required MST identifier, so there is nothing to `create({})`.
  */
 export function getConfigurationSchemaDefinition(nodeOrType) {
-    return getConfigurationSchemaMetadata(isType(nodeOrType) ? nodeOrType : getType(nodeOrType))?.definition;
-}
-/**
- * The construction options a live config node's schema was built with
- * (identifier kind, `explicitlyTyped`, the `preProcessSnapshot` hook). Undefined
- * when the node's type isn't a registered configuration schema.
- */
-export function getConfigurationSchemaOptions(node) {
-    return getConfigurationSchemaMetadata(getType(node))?.options;
+    return getConfigurationSchemaMetadata(nodeOrType)?.definition;
 }

package/esm/configuration/schemaTypes.d.ts

@@ -1,14 +1,16 @@
 import type { ConfigSlotDefinition } from './configurationSlot.ts';
+import type { ConfigurationSchemaMetadata } from './schemaRegistry.ts';
 import type { AnyConfigurationModel, AnyConfigurationSchemaType } from './types.ts';
 /**
- * given a union of explicitly typed configuration schema types,
- * extract an array of the type names contained in the union
- *
- * @param unionType -
- * @returns Array of type names contained in the union
+ * The names an explicitly typed union's members answer to, each the name its
+ * schema was given, read through whatever wraps the union — a pluggable
+ * union's `snapshotProcessor`, a `maybe`, a `types.late`. A member that is
+ * itself a union contributes its own; a member with no type of its own throws.
  */
 export declare function getTypeNamesFromExplicitlyTypedUnion(maybeUnionType: unknown): string[];
+/** The type `ConfigurationSchema()` built, by any handle on it (`schemaRegistry.ts`). */
 export declare function isBareConfigurationSchemaType(thing: unknown): thing is AnyConfigurationSchemaType;
+/** A schema, or a union, array or map of them. */
 export declare function isConfigurationSchemaType(thing: unknown): thing is AnyConfigurationSchemaType;
 /**
  * A configuration schema definition maps each key to exactly one of three kinds
@@ -21,3 +23,17 @@ export declare function isConfigurationSchemaType(thing: unknown): thing is AnyC
 export declare function isConstantEntry(def: unknown): def is string | number;
 export declare function isSlotDefinitionEntry(def: unknown): def is ConfigSlotDefinition;
 export declare function isConfigurationModel(thing: unknown): thing is AnyConfigurationModel;
+/** A bare value a schema's `shorthand` lifts. */
+export type ShorthandForm = 'string' | 'number';
+/**
+ * The slot a bare value of each form lifts into, off a `shorthand` option:
+ * each slot it names takes the form its own type holds, a number where it
+ * holds one (`rules: [7.3]`) and a string otherwise (`color: 'red'`), so a
+ * width naming `value` and `field` reads `size: 3` as the one and
+ * `size: 'score'` as the other.
+ */
+export declare function shorthandTargetsOf(definition: Record<string, unknown>, shorthand: string | readonly string[] | undefined): Partial<Record<ShorthandForm, string>>;
+/** The shorthand form of a bare value, or undefined for any other value. */
+export declare function bareFormOf(value: unknown): ShorthandForm | undefined;
+/** {@link shorthandTargetsOf} a registered schema. */
+export declare function shorthandTargets({ definition, options, }: ConfigurationSchemaMetadata): Partial<Record<ShorthandForm, string>>;