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

package/esm/configuration/configurationSlot.js

@@ -1,7 +1,18 @@
 import { types } from '@jbrowse/mobx-state-tree';
+import { isCssColor } from '../util/cssColorParse.js';
 import { isJexl, stringToJexlExpression } from '../util/jexlStrings.js';
 import { FileLocation } from '../util/types/mst.js';
 import { isCallbackValue } from './slotValueUtils.js';
+// What a color slot admits is what the painters parse (`isCssColor`), plus the
+// empty string a slot such as `outlineColor` spells "none" with; a field name
+// written where a color goes used to load and paint the invalid sentinel.
+function notAColor(value) {
+    return `${JSON.stringify(value)} is not a color. A color is a CSS color: a name like "red" or "steelblue", "#rgb" / "#rrggbb" / "#rrggbbaa", "rgb()" / "rgba()" / "hsl()" / "hsla()", or "transparent"; a color computed per feature is a "jexl:" callback, in a slot that takes one`;
+}
+const CssColorType = types.refinement('CssColor', types.string, value => value === '' || isCssColor(value), notAColor);
+// An entry of a colour list has no "none" to spell, so '' is refused with the
+// rest of what is not a colour.
+const CssColorEntryType = types.refinement('CssColorEntry', types.string, isCssColor, notAColor);
 // Single source of truth for the builtin slot type names, pairing each with its
 // MST value type and its editor fallback default. Keeping model + fallback in
 // one table means adding a slot type is one edit and can't half-register.
@@ -13,15 +24,14 @@ import { isCallbackValue } from './slotValueUtils.js';
 // of.
 const slotTypes = {
     stringArray: { model: types.array(types.string), fallbackDefault: [] },
+    colorArray: { model: types.array(CssColorEntryType), fallbackDefault: [] },
     stringArrayMap: {
         model: types.map(types.array(types.string)),
         fallbackDefault: {},
     },
     numberMap: { model: types.map(types.number), fallbackDefault: {} },
     boolean: { model: types.boolean, fallbackDefault: true },
-    // a color is just a string; the editor picks a color widget off the slot's
-    // `type` metadata, and values are accepted unvalidated (CSS names, hex, jexl)
-    color: { model: types.string, fallbackDefault: 'black' },
+    color: { model: CssColorType, fallbackDefault: 'black' },
     integer: { model: types.integer, fallbackDefault: 1 },
     number: { model: types.number, fallbackDefault: 1 },
     // The `maybe*` types spend `undefined` on "not explicitly set", which is the
@@ -31,11 +41,17 @@ const slotTypes = {
     maybeBoolean: { model: types.maybe(types.boolean) },
     // for a slot whose unset state means "decide from the data" — a feature's own
     // BED itemRgb, say
-    maybeColor: { model: types.maybe(types.string) },
-    // object-valued, e.g. alignments `colorBy`
+    maybeColor: { model: types.maybe(CssColorType) },
+    // object-valued, e.g. alignments `sortedBy`
     maybeFrozen: { model: types.maybe(types.frozen()) },
+    // for text whose unset state is a third thing beside some text and none: an
+    // axis title is derived while unset, and drawn bare once it is ''
+    maybeString: { model: types.maybe(types.string) },
     string: { model: types.string, fallbackDefault: '' },
     text: { model: types.string, fallbackDefault: '' },
+    // a field the display reads per feature: a name, a dotted path, or a
+    // `jexl:` expression, which the display evaluates and the reader never does
+    featureField: { model: types.string, fallbackDefault: '' },
     fileLocation: {
         model: FileLocation,
         fallbackDefault: {
@@ -45,10 +61,16 @@ const slotTypes = {
     },
     frozen: { model: types.frozen(), fallbackDefault: {} },
 };
-// The two types with no builtin table entry, because the author supplies the
-// `types.enumeration` as `model`. Named once, and spliced into both the type
-// union and the runtime set below so those two cannot drift apart.
-const ENUM_SLOT_TYPES = ['stringEnum', 'maybeStringEnum'];
+// The types with no builtin table entry, because the author supplies the
+// `types.enumeration` as `model` and `ConfigSlot` wraps it: in `types.maybe`
+// for `maybeStringEnum`, in `types.array` for `stringEnumArray`. Named once,
+// and spliced into both the type union and the runtime set below so those two
+// cannot drift apart.
+const ENUM_SLOT_TYPES = [
+    'stringEnum',
+    'maybeStringEnum',
+    'stringEnumArray',
+];
 /**
  * The same closed set, at runtime, because the type alone does not close it for
  * the callers that matter most: `ConfigSlot` is plugin-facing, and a JS plugin
@@ -82,15 +104,37 @@ const MAYBE_TYPES = new Set([
     'maybeStringEnum',
 ]);
 const JexlStringType = types.refinement('JexlString', types.string, isJexl);
+const CALLBACK_SLOTS = 'a slot that takes a callback declares the names it reads, which its config docs list as callback args';
+function notACallbackSlot(value) {
+    return `${JSON.stringify(value)} is a jexl: callback, and this slot takes a value: ${CALLBACK_SLOTS}`;
+}
+/** Why the slot `name`, of type `type`, refuses `value` on a write. */
+export function slotWriteRefusal(name, type, value) {
+    return isJexl(value)
+        ? `${name} takes no jexl: callback, and ${JSON.stringify(value)} is one: ${CALLBACK_SLOTS}`
+        : `${name} is a ${type} slot and cannot take ${JSON.stringify(value)}`;
+}
+function refusingCallbacks(model) {
+    return types.refinement(model, value => !isJexl(value), notACallbackSlot);
+}
 /**
- * A configuration slot is a plain value-union MST property: the slot's value
- * type, OR a `jexl:...` callback string. The value lives directly on the parent
- * configuration model — there is no per-slot sub-model. `types.stripDefault`
- * omits the property from the parent snapshot when it equals the default, so
- * saved sessions stay minimal. Per-slot metadata
- * (type/description/defaultValue/contextVariable) lives in the schema registry
- * (a WeakMap keyed by the MST type, see schemaRegistry.ts); jexl callbacks are
- * evaluated on read by `readConfObject`.
+ * A configuration slot is a plain MST property holding the slot's value type,
+ * or, where the slot declares a `contextVariable`, that or a `jexl:...`
+ * callback string. Every other slot refuses a `jexl:` string, so a callback
+ * the reader would evaluate is one the schema says it takes. A `featureField`
+ * holds a `jexl:` expression as its value, which the display evaluates per
+ * feature. The value lives directly on the parent configuration model — there
+ * is no per-slot sub-model. `types.stripDefault` omits the property from the
+ * parent snapshot when it equals the default, so saved sessions stay minimal.
+ * Per-slot metadata (type/description/defaultValue/contextVariable) lives in
+ * the schema registry (a WeakMap keyed by the MST type, see
+ * schemaRegistry.ts); jexl callbacks are evaluated on read by
+ * `readConfObject`.
+ *
+ * Interning the returned type on `(type, model, defaultValue)` was prototyped
+ * and declined: a session builds 1197 slot types for 222 distinct ones, and
+ * removing the repeats moves neither the time nor the heap
+ * (`config-schema-construction`, published in `reference/EAGER_BUNDLE.md`).
  */
 export default function ConfigSlot(definition) {
     const { model, type, defaultValue } = definition;
@@ -122,11 +166,28 @@ export default function ConfigSlot(definition) {
     if (defaultValue !== undefined && MAYBE_TYPES.has(type)) {
         throw new Error(`a "${type}" slot cannot have a concrete defaultValue (${JSON.stringify(defaultValue)}): unset is the state a maybe* slot exists for, and no config can spell undefined, so it would be unreachable. If this slot overrides a base slot, the base's defaultValue merged in — state 'defaultValue: undefined' to overwrite it. Otherwise use the non-maybe form of the type.`);
     }
-    return types.stripDefault(types.union(JexlStringType, 
-    // `maybeStringEnum` is the only maybe type whose model comes from the
-    // author: they write the plain vocabulary and the nullability is added
-    // here.
-    type === 'maybeStringEnum' ? types.maybe(valueModel) : valueModel), defaultValue);
+    const callback = !!definition.contextVariable?.length;
+    if (type === 'featureField' && callback) {
+        throw new Error('a "featureField" slot names a field the display reads per feature, and its jexl: expression is evaluated there, never called with a contextVariable. If this slot overrides a base callback slot, state \'contextVariable: undefined\'.');
+    }
+    if (!callback && isJexl(defaultValue)) {
+        throw new Error(`the defaultValue ${JSON.stringify(defaultValue)} is a jexl: callback, so the slot declares the contextVariable names it reads`);
+    }
+    const value = enumShaped(type, valueModel);
+    return types.stripDefault(callback
+        ? types.union(JexlStringType, value)
+        : type === 'featureField'
+            ? value
+            : refusingCallbacks(value), defaultValue);
+}
+// The author writes an enum slot's plain vocabulary, and the slot's shape
+// around it is added here.
+function enumShaped(type, model) {
+    return type === 'maybeStringEnum'
+        ? types.maybe(model)
+        : type === 'stringEnumArray'
+            ? types.array(model)
+            : model;
 }
 /**
  * New value when converting a fixed-value slot to a jexl callback. Already-

package/esm/configuration/formatAboutConfigSchema.d.ts

@@ -28,28 +28,14 @@
  * ```
  */
 export declare function FormatAboutConfigSchemaFactory(): import("./configurationSchema.ts").ConfigurationSchemaType<{
-    /**
-     * #slot formatAbout.config
-     * callback returning an object of fields to merge over the config shown
-     */
     readonly config: {
-        readonly type: "frozen";
-        readonly description: "formats configuration object in about dialog";
-        readonly defaultValue: {};
-        readonly contextVariable: ["config"];
+        type: "frozen";
+    } & {
+        defaultValue: unknown;
     };
-    /**
-     * #slot formatAbout.hideUris
-     * leave file locations out of the About dialog, for a deployment that would
-     * rather not show users where the data sits. Hides URIs and local paths
-     * alike, drops the "Copy config" button, and suppresses the File info panel
-     * — a BAM's `@SQ UR:` and `@PG CL:` lines are locations too. "Show ref
-     * names" stays, since it exposes none. The two tiers are OR'd, so a
-     * session-wide `true` cannot be turned back on by a track. It hides the
-     * locations from the dialog only, not from `config.json`
-     */
     readonly hideUris: {
-        readonly type: "boolean";
-        readonly defaultValue: false;
+        type: "boolean";
+    } & {
+        defaultValue: boolean;
     };
-}, import("./configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;
+}, import("./configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined, undefined, import("./requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>>>;

package/esm/configuration/formatDetailsConfigSchema.d.ts

@@ -1,7 +1,7 @@
 /**
  * Levels of subfeature the `subfeatures` callback runs on when no tier sets
- * `depth`. Lives here rather than as the slot's `defaultValue` because the slot
- * has to be able to say "unset": see the `depth` slot's own comment.
+ * `depth`. Applied by the reader rather than as the slot's `defaultValue`, so
+ * the slot can still read as unset and the session's value reach a track.
  */
 export declare const DEFAULT_FORMAT_DETAILS_DEPTH = 2;
 /**
@@ -35,46 +35,20 @@ export declare const DEFAULT_FORMAT_DETAILS_DEPTH = 2;
  * ```
  */
 export declare function FormatDetailsConfigSchemaFactory(): import("./configurationSchema.ts").ConfigurationSchemaType<{
-    /**
-     * #slot formatDetails.feature
-     * callback returning an object of fields to merge onto the clicked feature.
-     * A plain object works too, for fields that are the same on every feature
-     */
     readonly feature: {
-        readonly type: "frozen";
-        readonly description: "adds extra fields to the feature details";
-        readonly defaultValue: {};
-        readonly contextVariable: ["feature"];
+        type: "frozen";
+    } & {
+        defaultValue: unknown;
     };
-    /**
-     * #slot formatDetails.subfeatures
-     * the same, applied to each subfeature down to `depth`
-     */
     readonly subfeatures: {
-        readonly type: "frozen";
-        readonly description: "adds extra fields to the subfeatures of a feature";
-        readonly defaultValue: {};
-        readonly contextVariable: ["feature"];
+        type: "frozen";
+    } & {
+        defaultValue: unknown;
     };
-    /**
-     * #slot formatDetails.depth
-     * how many levels of subfeature the `subfeatures` callback runs on,
-     * defaulting to 2, which stops at a gene's transcripts rather than
-     * descending into their exons and CDSs. A track's value wins over the
-     * session's
-     */
     readonly depth: {
-        readonly type: "maybeNumber";
-        readonly description: "levels of subfeature the formatDetails.subfeatures callback runs on, default 2";
+        type: "maybeNumber";
     };
-    /**
-     * #slot formatDetails.maxDepth
-     * how many levels of subfeature card the panel renders at all, which is a
-     * separate question from how deep `subfeatures` formats. Unset means no
-     * limit. A track's value wins over the session's
-     */
     readonly maxDepth: {
-        readonly type: "maybeNumber";
-        readonly description: "hide subfeatures nested deeper than this, default no limit";
+        type: "maybeNumber";
     };
-}, import("./configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined>>;
+}, import("./configurationSchema.ts").ConfigurationSchemaOptions<undefined, undefined, undefined, import("./requirements.ts").ConfigurationSchemaRequirement<Partial<Record<string, string[]>>, string>>>;

package/esm/configuration/formatDetailsConfigSchema.js

@@ -1,8 +1,8 @@
 import { ConfigurationSchema } from './configurationSchema.js';
 /**
  * Levels of subfeature the `subfeatures` callback runs on when no tier sets
- * `depth`. Lives here rather than as the slot's `defaultValue` because the slot
- * has to be able to say "unset": see the `depth` slot's own comment.
+ * `depth`. Applied by the reader rather than as the slot's `defaultValue`, so
+ * the slot can still read as unset and the session's value reach a track.
  */
 export const DEFAULT_FORMAT_DETAILS_DEPTH = 2;
 /**
@@ -40,23 +40,27 @@ export function FormatDetailsConfigSchemaFactory() {
         /**
          * #slot formatDetails.feature
          * callback returning an object of fields to merge onto the clicked feature.
-         * A plain object works too, for fields that are the same on every feature
+         * `track` is the track's config, so one session-wide callback can link out
+         * per assembly or name the track. A plain object works too, for fields
+         * that are the same on every feature
          */
         feature: {
             type: 'frozen',
             description: 'adds extra fields to the feature details',
             defaultValue: {},
-            contextVariable: ['feature'],
+            contextVariable: ['feature', 'track'],
         },
         /**
          * #slot formatDetails.subfeatures
-         * the same, applied to each subfeature down to `depth`
+         * the same, applied to each subfeature down to `depth`. `parent` is the
+         * feature it sits in and `depth` how far down, 1 for a gene's transcript
+         * and 2 for the transcript's exon
          */
         subfeatures: {
             type: 'frozen',
             description: 'adds extra fields to the subfeatures of a feature',
             defaultValue: {},
-            contextVariable: ['feature'],
+            contextVariable: ['feature', 'parent', 'depth', 'track'],
         },
         /**
          * #slot formatDetails.depth
@@ -66,11 +70,6 @@ export function FormatDetailsConfigSchemaFactory() {
          * session's
          */
         depth: {
-            // `maybeNumber`, so unset is expressible. With a `defaultValue` the two
-            // tiers cannot be told apart -- a plain number slot reads back its own
-            // default, so "the track set 2" and "the track set nothing" are the same
-            // read, and the session-wide value can never apply to a track. The
-            // resolved default is DEFAULT_FORMAT_DETAILS_DEPTH, applied by the reader
             type: 'maybeNumber',
             description: 'levels of subfeature the formatDetails.subfeatures callback runs on, default 2',
         },
@@ -81,8 +80,6 @@ export function FormatDetailsConfigSchemaFactory() {
          * limit. A track's value wins over the session's
          */
         maxDepth: {
-            // `maybeNumber` for the same reason as `depth`, and here unset is also
-            // the meaningful value: no limit at all
             type: 'maybeNumber',
             description: 'hide subfeatures nested deeper than this, default no limit',
         },

package/esm/configuration/getConf.d.ts

@@ -1,4 +1,4 @@
-import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValue } from './types.ts';
+import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue } from './types.ts';
 /**
  * #api core/configuration
  * Reads a configuration value from a state model that has a `.configuration`
@@ -19,13 +19,21 @@ import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSche
 export declare function getConf(model: {
     configuration: AnyConfigurationModel;
 }): AnyConfigurationSnapshot;
-export declare function getConf<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | string[] = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(model: {
+export declare function getConf<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(model: {
     configuration: CONFMODEL;
-}, slotPath: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : any;
+}, slotPath: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : ConfigurationSlotPathValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT>;
 /**
  * #api core/configuration
- * Write counterpart to `getConf`: sets a slot on a state model that has a
- * `.configuration` member (a track or display state model).
+ * Write counterpart to `getConf`, and it takes the same path: a slot name, or
+ * an array naming a sub-schema's member at any depth —
+ * `setConf(self, ['scales', 'y', 'domainMin'], 5)`. Takes the display or track
+ * model, or a config node directly.
+ *
+ * **The path length says what the write replaces.** A path ending on a slot
+ * writes that slot and leaves the object around it alone; a path ending on a
+ * sub-schema replaces the whole object, which is how a channel whose members
+ * move together — a facet's field and the domain that field's values order —
+ * gets written without a stale member surviving underneath.
  *
  * **Prefer this over a bare `self.configuration.setSlot('x', v)`.** The
  * constraint here mirrors `getConf`'s, so on a model with a concrete schema an
@@ -49,10 +57,10 @@ export declare function getConf<CONFMODEL extends AnyConfigurationModel, SLOT ex
  * `undefined` is a legitimate write — it resets a slot to its schema default —
  * and the declared slot value type doesn't include it.
  *
- * @param model - object containing a 'configuration' member
- * @param slotName - the slot to write
+ * @param target - a model with a `configuration` member, or a config node
+ * @param slotPath - the slot to write, or the path to one
  * @param value - the new value
  */
-export declare function setConf<CONFMODEL extends AnyConfigurationModel, SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(model: {
+export declare function setConf<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(target: CONFMODEL | {
     configuration: CONFMODEL;
-}, slotName: SLOT, value: unknown): void;
+}, slotPath: SLOT, value: unknown): void;

package/esm/configuration/getConf.js

@@ -1,11 +1,22 @@
+import { getType, isArrayType } from '@jbrowse/mobx-state-tree';
 import { readConfObject } from './readConfObject.js';
+import { getConfigurationSchemaDefinition } from './schemaRegistry.js';
+import { isConfigurationModel, isConfigurationSchemaType, } from './schemaTypes.js';
 export function getConf(model, slotPath, args = {}) {
     return readConfObject(model.configuration, slotPath, args);
 }
 /**
  * #api core/configuration
- * Write counterpart to `getConf`: sets a slot on a state model that has a
- * `.configuration` member (a track or display state model).
+ * Write counterpart to `getConf`, and it takes the same path: a slot name, or
+ * an array naming a sub-schema's member at any depth —
+ * `setConf(self, ['scales', 'y', 'domainMin'], 5)`. Takes the display or track
+ * model, or a config node directly.
+ *
+ * **The path length says what the write replaces.** A path ending on a slot
+ * writes that slot and leaves the object around it alone; a path ending on a
+ * sub-schema replaces the whole object, which is how a channel whose members
+ * move together — a facet's field and the domain that field's values order —
+ * gets written without a stale member surviving underneath.
  *
  * **Prefer this over a bare `self.configuration.setSlot('x', v)`.** The
  * constraint here mirrors `getConf`'s, so on a model with a concrete schema an
@@ -29,11 +40,45 @@ export function getConf(model, slotPath, args = {}) {
  * `undefined` is a legitimate write — it resets a slot to its schema default —
  * and the declared slot value type doesn't include it.
  *
- * @param model - object containing a 'configuration' member
- * @param slotName - the slot to write
+ * @param target - a model with a `configuration` member, or a config node
+ * @param slotPath - the slot to write, or the path to one
  * @param value - the new value
  */
-export function setConf(model, slotName, value) {
-    // eslint-disable-next-line no-restricted-syntax -- this is setConf
-    model.configuration.setSlot(slotName, value);
+export function setConf(target, slotPath, value) {
+    writeConfPath(isConfigurationModel(target) ? target : target.configuration, typeof slotPath === 'string' ? [slotPath] : slotPath, value);
+}
+/**
+ * Walk to the node the last segment names a member of, then write that member
+ * through whichever of the node's three write actions the member is: a
+ * sub-schema is replaced, an array of sub-schemas is replaced, and a slot goes
+ * through `setSlot` so ADR-052's name guard and the value-type guard both run.
+ * MST's `applyPatch` takes the same path and runs neither guard.
+ */
+function writeConfPath(conf, path, value) {
+    if (!path.length) {
+        throw new Error('setConf needs a slot name or a path to one');
+    }
+    let node = conf;
+    for (const segment of path.slice(0, -1)) {
+        const child = node[segment];
+        if (!isConfigurationModel(child)) {
+            throw new Error(`${getType(node).name} has no sub-schema "${segment}", so ${path.join('.')} names nothing to write`);
+        }
+        node = child;
+    }
+    const leaf = path.at(-1);
+    // Classify off the declaration, never off what the member holds: a
+    // `stringArray` slot holds an array node, and an optional sub-schema nobody
+    // has written yet holds nothing.
+    const declared = getConfigurationSchemaDefinition(node)?.[leaf];
+    if (!isConfigurationSchemaType(declared)) {
+        // eslint-disable-next-line no-restricted-syntax -- this is setConf
+        node.setSlot(leaf, value);
+    }
+    else if (isArrayType(declared)) {
+        node.setSubschemaArray(leaf, value);
+    }
+    else {
+        node.setSubschema(leaf, value);
+    }
 }

package/esm/configuration/index.d.ts

@@ -1,18 +1,25 @@
 export { ConfigurationReference, ConfigurationSchema, hydrateTrackConfig, } from './configurationSchema.ts';
 export type { ConfigurationSchemaDefinition } from './configurationSchema.ts';
-export type { AnyConfiguration, AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSnapshot, ConfigModelForFields, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotValue, ConfigurationSnapshot, HostChecksSlotNames, } from './types.ts';
-export { getConfigurationSchemaDefinition, getConfigurationSchemaMetadata, } from './schemaRegistry.ts';
+export { ConfigurationSchemaUnion, arraySlotUnion, } from './configurationSchemaUnion.ts';
+export type { ConfigurationSchemaUnionType } from './configurationSchemaUnion.ts';
+export type { ConfigSlotDefinition } from './configurationSlot.ts';
+export type { AnyConfiguration, AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSnapshot, ConfigModelForFields, ConfigNodeActions, ConfigNodeBrand, ConfigNodeProps, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue, ConfigurationSnapshot, HostChecksSlotNames, IdentifierSlotDef, TypeSlotDef, } from './types.ts';
+export { getConfigurationSchemaDefinition, getConfigurationSchemaOptions, getConfigurationSchemaMetadata, getConfigurationSchemaUnion, } from './schemaRegistry.ts';
+export type { ConfigurationSchemaUnionMetadata } from './schemaRegistry.ts';
 export { getTypeNamesFromExplicitlyTypedUnion, isBareConfigurationSchemaType, isConfigurationModel, isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.ts';
 export { FormatAboutConfigSchemaFactory } from './formatAboutConfigSchema.ts';
 export { DEFAULT_FORMAT_DETAILS_DEPTH, FormatDetailsConfigSchemaFactory, } from './formatDetailsConfigSchema.ts';
 export { mergeFormatCallbacks } from './mergeFormatCallbacks.ts';
-export { readConfObject, readConfSlot, readConfigValue, } from './readConfObject.ts';
+export { readConfObject, readConfigValue } from './readConfObject.ts';
 export { getConf, setConf } from './getConf.ts';
 export { fillLocations } from './fillLocations.ts';
+export { preProcessConfigSnapshot, preProcessSnapshotWith, shorthandForm, } from './snapshotPreprocess.ts';
+export { requirementProblems } from './requirements.ts';
+export type { ConfigurationSchemaRequirement, RequirementProblem, } from './requirements.ts';
 export { expandTabixShorthand, tabixIndexSnapshot } from './tabixShorthand.ts';
 export { tabixIndexFields } from './tabixIndexFields.ts';
 export { evaluateJexl, isCallbackValue } from './slotValueUtils.ts';
 export { toCallbackValue, toFixedValue } from './configurationSlot.ts';
-export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, preProcessSlotValues, slotChoices, } from './slotFacade.ts';
+export { getSlotDefinition, isConfigurationSlot, isConfigurationSubschema, makeSlotFacade, mergedSubschemaValue, preProcessSlotValues, slotChoices, slotValueRefusal, } from './slotFacade.ts';
 export type { SlotFacade } from './slotFacade.ts';
 export { fullConfSnapshot } from './fullConfSnapshot.ts';

package/esm/configuration/index.js

@@ -1,20 +1,23 @@
 export { ConfigurationReference, ConfigurationSchema, hydrateTrackConfig, } from './configurationSchema.js';
-export { getConfigurationSchemaDefinition, 
+export { ConfigurationSchemaUnion, arraySlotUnion, } from './configurationSchemaUnion.js';
+export { getConfigurationSchemaDefinition, getConfigurationSchemaOptions, 
 // exported for scripts/generateConfigManifest.ts, which needs the
 // preProcessSnapshot off a schema whose pluggable type does not expose one —
 // TextSearchAdapterType, where the shorthand is nonetheless the documented
 // way to write the config
-getConfigurationSchemaMetadata, } from './schemaRegistry.js';
+getConfigurationSchemaMetadata, getConfigurationSchemaUnion, } from './schemaRegistry.js';
 export { getTypeNamesFromExplicitlyTypedUnion, isBareConfigurationSchemaType, isConfigurationModel, isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.js';
 export { FormatAboutConfigSchemaFactory } from './formatAboutConfigSchema.js';
 export { DEFAULT_FORMAT_DETAILS_DEPTH, FormatDetailsConfigSchemaFactory, } from './formatDetailsConfigSchema.js';
 export { mergeFormatCallbacks } from './mergeFormatCallbacks.js';
-export { readConfObject, readConfSlot, readConfigValue, } from './readConfObject.js';
+export { readConfObject, readConfigValue } from './readConfObject.js';
 export { getConf, setConf } from './getConf.js';
 export { fillLocations } from './fillLocations.js';
+export { preProcessConfigSnapshot, preProcessSnapshotWith, shorthandForm, } from './snapshotPreprocess.js';
+export { requirementProblems } from './requirements.js';
 export { expandTabixShorthand, tabixIndexSnapshot } from './tabixShorthand.js';
 export { tabixIndexFields } from './tabixIndexFields.js';
 export { evaluateJexl, isCallbackValue } from './slotValueUtils.js';
 export { toCallbackValue, toFixedValue } from './configurationSlot.js';
-export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, preProcessSlotValues, slotChoices, } from './slotFacade.js';
+export { getSlotDefinition, isConfigurationSlot, isConfigurationSubschema, makeSlotFacade, mergedSubschemaValue, preProcessSlotValues, slotChoices, slotValueRefusal, } from './slotFacade.js';
 export { fullConfSnapshot } from './fullConfSnapshot.js';

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,6 +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 { AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue } from './types.ts';
 import type { IMSTMap } from '@jbrowse/mobx-state-tree';
 /**
  * #api core/configuration
@@ -25,7 +25,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<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>;
 export declare function readConfObject(confObject: IMSTMap<AnyConfigurationSchemaType>, slotPath?: string | string[], args?: Record<string, unknown>): any;
 /**
  * Read a value from a plain config snapshot object. Automatically evaluates
@@ -34,23 +34,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;