@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/configuration/readConfObject.js

@@ -0,0 +1,118 @@
+/**
+ * @module
+ * 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, 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
+// env. readConfObject only ever operates on live MST configs — nested sub-config
+// reads stay MST (env resolves to the root), and frozen track configs hydrate to
+// MST before any callback is read — so the env instance is always present here.
+function evalConfigCallback(expr, args, confObject) {
+    if (!isStateTreeNode(confObject)) {
+        // A jexl slot needs the realm's jexl instance, which is read from a live
+        // config node's env. A plain config snapshot (e.g. an un-hydrated
+        // session.tracks entry) carries no env — read it through a hydrated model,
+        // or use readConfigValue(config, key, feature, jexl) which takes jexl
+        // explicitly.
+        throw new Error(`cannot evaluate jexl config callback ${JSON.stringify(expr)}: config is a plain snapshot, not a live model (no env to resolve the jexl instance)`);
+    }
+    const jexl = getEnv(confObject)
+        .pluginManager?.jexl;
+    if (!jexl) {
+        throw new Error(`cannot evaluate jexl config callback ${JSON.stringify(expr)}: no pluginManager jexl instance in config env`);
+    }
+    return evaluateJexl(expr, args, jexl);
+}
+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 = confObject[slotName];
+    if (value === undefined) {
+        return undefined;
+    }
+    const val = isCallbackValue(value) && !isFeatureField(confObject, slotName)
+        ? evalConfigCallback(value, args, confObject)
+        : value;
+    // Fast path for primitives (most common case)
+    if (val === null || typeof val !== 'object') {
+        return val;
+    }
+    // Return the live, referentially-stable snapshot (frozen in dev) rather than
+    // a per-read clone: stable identity lets downstream computeds memoize, and
+    // the old structuredClone was both a hot-path allocation and a source of
+    // spurious recomputation. Treat as read-only.
+    return isStateTreeNode(val) ? getSnapshot(val) : val;
+}
+// loose implementation signature: the body returns values that are `any` by
+// 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
+    // one-element array on the way past
+    if (typeof slotPath === 'string') {
+        return readSlot(confObject, slotPath, args);
+    }
+    if (slotPath !== undefined && !Array.isArray(slotPath)) {
+        throw new TypeError('slotPath must be a string or array');
+    }
+    // No path, or an empty one — which means the same thing, and used not to: `[]`
+    // is truthy, so it reached the walk below and read `confObject[undefined]`.
+    //
+    // Returns the whole config as a plain object: the live, referentially-stable
+    // snapshot (frozen in dev), not a fresh clone — treat as read-only.
+    if (!slotPath?.length) {
+        return isStateTreeNode(confObject) ? getSnapshot(confObject) : confObject;
+    }
+    // every segment but the last names a sub-config, and only the last is a slot
+    // read — which is where jexl evaluation and snapshotting happen, and nowhere
+    // else. Iterative rather than a self-call per segment, which re-entered the
+    // whole argument-shape preamble above at each level.
+    let conf = confObject;
+    for (let i = 0; i < slotPath.length - 1; i++) {
+        const subConf = conf[slotPath[i]];
+        if (subConf === undefined) {
+            return undefined;
+        }
+        conf = subConf;
+    }
+    return readSlot(conf, slotPath[slotPath.length - 1], args);
+}
+// 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;
+        for (const k of key) {
+            val = val?.[k];
+        }
+        return val;
+    }
+    return config[key];
+}
+/**
+ * Read a value from a plain config snapshot object. Automatically evaluates
+ * "jexl:..." strings per-feature. Works without MST — intended for use in
+ * rendering code (GPU, Canvas2D, workers). Pass the realm's `pluginManager.jexl`
+ * so plugin-registered functions (e.g. in a custom `mouseover` slot) resolve.
+ */
+export function readConfigValue(config, key, feature, jexl) {
+    const raw = resolveConfigValue(config, key);
+    return (isCallbackValue(raw) ? evaluateJexl(raw, { feature }, jexl) : raw);
+}

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

@@ -0,0 +1,52 @@
+import type { ConfigurationSchemaDefinition, MergedConfigurationSchemaOptions } from './configurationSchema.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;
+    /**
+     * construction options (identifier kind, baseConfiguration, etc.) as stored,
+     * 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;
+/**
+ * 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 and `fullConfSnapshot`.
+ *
+ * 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;

package/esm/configuration/schemaRegistry.js

@@ -0,0 +1,48 @@
+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);
+}
+/**
+ * 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(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 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 and `fullConfSnapshot`.
+ *
+ * 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(nodeOrType)?.definition;
+}

package/esm/configuration/schemaTypes.d.ts

@@ -0,0 +1,39 @@
+import type { ConfigSlotDefinition } from './configurationSlot.ts';
+import type { ConfigurationSchemaMetadata } from './schemaRegistry.ts';
+import type { AnyConfigurationModel, AnyConfigurationSchemaType } from './types.ts';
+/**
+ * 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
+ * of entry:
+ *
+ *  - constant   → a bare string/number (becomes a volatile instance constant)
+ *  - slot       → a ConfigSlotDefinition object (has a `type` field, not a type)
+ *  - sub-schema → an MST configuration-schema type, see isConfigurationSchemaType
+ */
+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>>;

package/esm/configuration/schemaTypes.js

@@ -0,0 +1,105 @@
+/**
+ * @module
+ * Recognizing configuration schemas and classifying the entries in one. These
+ * predicates are the single source of truth for both questions — shared by
+ * schema construction, every reader, and the config editor — so "is this a
+ * config schema?" and "what kind of entry is this?" have one answer everywhere.
+ */
+import { asArrayType, asMapType, getType, getUnionSubtypes, isStateTreeNode, isType, isUnionType, } from '@jbrowse/mobx-state-tree';
+import { getConfigurationSchemaMetadata, isRegisteredConfigurationSchema, } from './schemaRegistry.js';
+/**
+ * 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 function getTypeNamesFromExplicitlyTypedUnion(maybeUnionType) {
+    if (!isType(maybeUnionType) || !isUnionType(maybeUnionType)) {
+        return [];
+    }
+    return getUnionSubtypes(maybeUnionType).flatMap(member => {
+        const meta = getConfigurationSchemaMetadata(member);
+        if (meta?.options.explicitlyTyped) {
+            return [meta.name];
+        }
+        if (isUnionType(member)) {
+            return getTypeNamesFromExplicitlyTypedUnion(member);
+        }
+        // the branch a `maybe`-like union adds so the slot can be absent
+        if (member.name === 'undefined') {
+            return [];
+        }
+        throw new Error(`invalid config schema type ${member.name}`);
+    });
+}
+/** The type `ConfigurationSchema()` built, by any handle on it (`schemaRegistry.ts`). */
+export function isBareConfigurationSchemaType(thing) {
+    return isType(thing) && isRegisteredConfigurationSchema(thing);
+}
+/** A schema, or a union, array or map of them. */
+export function isConfigurationSchemaType(thing) {
+    if (!isType(thing)) {
+        return false;
+    }
+    if (isBareConfigurationSchemaType(thing)) {
+        return true;
+    }
+    if (isUnionType(thing)) {
+        return getUnionSubtypes(thing).every(t => isConfigurationSchemaType(t) || t.name === 'undefined');
+    }
+    const collection = asArrayType(thing) ?? asMapType(thing);
+    return !!collection && isConfigurationSchemaType(collection.getChildType());
+}
+/**
+ * A configuration schema definition maps each key to exactly one of three kinds
+ * of entry:
+ *
+ *  - constant   → a bare string/number (becomes a volatile instance constant)
+ *  - slot       → a ConfigSlotDefinition object (has a `type` field, not a type)
+ *  - sub-schema → an MST configuration-schema type, see isConfigurationSchemaType
+ */
+export function isConstantEntry(def) {
+    return typeof def === 'string' || typeof def === 'number';
+}
+export function isSlotDefinitionEntry(def) {
+    return (typeof def === 'object' && def !== null && !isType(def) && 'type' in def);
+}
+export function isConfigurationModel(thing) {
+    return isStateTreeNode(thing) && isConfigurationSchemaType(getType(thing));
+}
+const NUMBER_SLOT_TYPES = new Set(['number', 'integer', 'maybeNumber']);
+/**
+ * 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 function shorthandTargetsOf(definition, shorthand) {
+    const slots = shorthand === undefined
+        ? []
+        : typeof shorthand === 'string'
+            ? [shorthand]
+            : shorthand;
+    return Object.fromEntries(slots.map(slot => {
+        const entry = definition[slot];
+        return [
+            isSlotDefinitionEntry(entry) && NUMBER_SLOT_TYPES.has(entry.type)
+                ? 'number'
+                : 'string',
+            slot,
+        ];
+    }));
+}
+/** The shorthand form of a bare value, or undefined for any other value. */
+export function bareFormOf(value) {
+    return typeof value === 'string'
+        ? 'string'
+        : typeof value === 'number'
+            ? 'number'
+            : undefined;
+}
+/** {@link shorthandTargetsOf} a registered schema. */
+export function shorthandTargets({ definition, options, }) {
+    return shorthandTargetsOf(definition, options.shorthand);
+}

package/esm/configuration/slotFacade.d.ts

@@ -0,0 +1,65 @@
+import type PluginManager from '../PluginManager.ts';
+import type { ConfigSlotDefinition, ConfigSlotType } from './configurationSlot.ts';
+import type { AnyConfigurationModel } from './types.ts';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
+/**
+ * Whether `slotName` on a config node is a slot (vs a nested sub-schema or a
+ * string/number constant).
+ */
+export declare function isConfigurationSlot(node: AnyConfigurationModel, slotName: string): boolean;
+/**
+ * Why a config of type `schema` cannot hold `value` at `key`, or undefined
+ * when it can: the schema's own lift first, then the slot's type, or a
+ * sub-schema's lift and checks. Also undefined for a key the schema does not
+ * declare, which is a question for its caller.
+ */
+export declare function slotValueRefusal(schema: IAnyType, key: string, value: unknown): string | undefined;
+/**
+ * The duck-typed object the config editor's leaf components consume. They never
+ * touch MST internals — only this shape (see ColorEditor.test.tsx, which passes
+ * a plain object). It is built from `(parentNode, slotName)` + the schema
+ * metadata table. Collection editors edit immutably via `set` (build a new
+ * array/map and assign it).
+ */
+export interface SlotFacade {
+    name: string;
+    description: string;
+    type: ConfigSlotType;
+    contextVariable: string[];
+    defaultValue: unknown;
+    /**
+     * enum choices, present only for the enum slot types; a `stringEnumArray`'s
+     * are the choices of each entry
+     */
+    choices?: string[];
+    pluginManager: PluginManager;
+    readonly value: unknown;
+    /**
+     * Whether the slot holds a non-default value. Each slot is `stripDefault`-
+     * wrapped, so an at-default slot is omitted from the config snapshot — the
+     * same signal the persistence/delta layer uses (robust for map/array slots
+     * where a live-value `deepEqual` against the plain default would misfire).
+     */
+    readonly modified: boolean;
+    set: (val: unknown) => void;
+}
+/**
+ * The vocabulary an enum slot offers, or undefined for any other slot. Reads the
+ * author's own `types.enumeration` off `model` — the enum types are the only
+ * ones the editor takes choices from, so a slot typed anything else renders as
+ * free text however valid its `model` is.
+ *
+ * Shared by the config editor's facade below and by
+ * `ConfigSlotDefaults.test.ts`, which snapshots every schema's vocabularies:
+ * dropping a member is a silent compatibility break, since a saved session
+ * holding it fails MST validation and the track then fails to hydrate.
+ */
+export declare function slotChoices(def: ConfigSlotDefinition): string[] | undefined;
+/**
+ * Look up a slot's metadata (type/description/defaultValue/contextVariable/
+ * model) from the schema-type table stashed by ConfigurationSchema. Includes
+ * slots inherited via `baseConfiguration`, which are merged into the table at
+ * schema construction.
+ */
+export declare function getSlotDefinition(node: AnyConfigurationModel, slotName: string): ConfigSlotDefinition;
+export declare function makeSlotFacade(node: AnyConfigurationModel, slotName: string): SlotFacade;

package/esm/configuration/slotFacade.js

@@ -0,0 +1,110 @@
+import { asModelType, getSnapshot } from '@jbrowse/mobx-state-tree';
+import { getEnumerationValues } from '../util/mst-reflection.js';
+import { getEnv } from '../util/mstUtils.js';
+import { slotWriteRefusal } from './configurationSlot.js';
+import { setConf } from './getConf.js';
+import { getConfigurationSchemaDefinition, getConfigurationSchemaMetadata, } from './schemaRegistry.js';
+import { isConfigurationSchemaType, isSlotDefinitionEntry, } from './schemaTypes.js';
+import { preProcessSnapshotWith } from './snapshotPreprocess.js';
+/**
+ * The slot's metadata entry, or undefined when `slotName` names a nested
+ * sub-schema or a string/number constant rather than a slot.
+ */
+function slotDefinition(node, slotName) {
+    const def = getConfigurationSchemaDefinition(node)?.[slotName];
+    return isSlotDefinitionEntry(def) ? def : undefined;
+}
+/**
+ * Whether `slotName` on a config node is a slot (vs a nested sub-schema or a
+ * string/number constant).
+ */
+export function isConfigurationSlot(node, slotName) {
+    return !!slotDefinition(node, slotName);
+}
+/**
+ * Why a config of type `schema` cannot hold `value` at `key`, or undefined
+ * when it can: the schema's own lift first, then the slot's type, or a
+ * sub-schema's lift and checks. Also undefined for a key the schema does not
+ * declare, which is a question for its caller.
+ */
+export function slotValueRefusal(schema, key, value) {
+    const meta = getConfigurationSchemaMetadata(schema);
+    const entry = meta?.definition[key];
+    if (!meta || entry === undefined) {
+        return undefined;
+    }
+    const subSchema = isConfigurationSchemaType(entry)
+        ? entry
+        : undefined;
+    // the slot's own property type, built once with the schema: what `setSlot`
+    // checks a write against
+    const slotType = asModelType(schema)?.properties[key];
+    try {
+        const lifted = preProcessSnapshotWith(meta, { [key]: value })[key];
+        if (subSchema) {
+            subSchema.create(lifted);
+        }
+        else if (isSlotDefinitionEntry(entry) && !slotType?.is(lifted)) {
+            return slotWriteRefusal(`${meta.name}.${key}`, entry.type, value);
+        }
+        return undefined;
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+}
+/**
+ * The vocabulary an enum slot offers, or undefined for any other slot. Reads the
+ * author's own `types.enumeration` off `model` — the enum types are the only
+ * ones the editor takes choices from, so a slot typed anything else renders as
+ * free text however valid its `model` is.
+ *
+ * Shared by the config editor's facade below and by
+ * `ConfigSlotDefaults.test.ts`, which snapshots every schema's vocabularies:
+ * dropping a member is a silent compatibility break, since a saved session
+ * holding it fails MST validation and the track then fails to hydrate.
+ */
+export function slotChoices(def) {
+    const { type, model } = def;
+    return (type === 'stringEnum' ||
+        type === 'maybeStringEnum' ||
+        type === 'stringEnumArray') &&
+        model
+        ? getEnumerationValues(model)
+        : undefined;
+}
+/**
+ * Look up a slot's metadata (type/description/defaultValue/contextVariable/
+ * model) from the schema-type table stashed by ConfigurationSchema. Includes
+ * slots inherited via `baseConfiguration`, which are merged into the table at
+ * schema construction.
+ */
+export function getSlotDefinition(node, slotName) {
+    const def = slotDefinition(node, slotName);
+    if (!def) {
+        throw new Error(`no slot metadata for ${slotName}`);
+    }
+    return def;
+}
+export function makeSlotFacade(node, slotName) {
+    const definition = getSlotDefinition(node, slotName);
+    const { type, description = '', defaultValue, contextVariable = [], } = definition;
+    return {
+        name: slotName,
+        description,
+        type,
+        contextVariable,
+        defaultValue,
+        choices: slotChoices(definition),
+        pluginManager: getEnv(node).pluginManager,
+        get value() {
+            return node[slotName];
+        },
+        get modified() {
+            return slotName in getSnapshot(node);
+        },
+        set(val) {
+            setConf(node, slotName, val);
+        },
+    };
+}