@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/configuration/configurationSchema.d.ts

@@ -1,9 +1,24 @@
+import type PluginManager from '../PluginManager.ts';
+import type { IsAny } from '../util/types/isAny.ts';
 import type { ConfigSlotDefinition } from './configurationSlot.ts';
-import type { AnyConfigurationSchemaType } from './types.ts';
-import type { IAnyType } from '@jbrowse/mobx-state-tree';
-export type { AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSlot, AnyConfigurationSlotType, } from './types.ts';
+import type { AnyConfigurationModel, AnyConfigurationSchemaType, GetInheritedIdentifier } from './types.ts';
+import type { IAnyType, IType, ReferenceIdentifier, SnapshotIn, SnapshotOut } from '@jbrowse/mobx-state-tree';
+export type { AnyConfigurationModel, AnyConfigurationSchemaType, } from './types.ts';
+/**
+ * The three entry kinds `makeConfigurationSchemaModel` classifies: a slot
+ * definition, a constant (bare string/number), or a nested sub-schema — which
+ * is the **MST type** `ConfigurationSchema()` returned, hence `IAnyType`.
+ *
+ * A raw nested `ConfigurationSchemaDefinition` used to be a fourth member here,
+ * and it was both dead and load-bearing in the wrong direction: nothing
+ * constructs a sub-schema from one (the loop has no branch for it, so it throws
+ * "no type set for config slot"), while a plain object of strings and numbers is
+ * exactly what a *slot definition* is — so every slot in the repo matched that
+ * member instead and was never checked against `ConfigSlotDefinition` at all.
+ * `type: 'enum'`, a name this system has never had, compiled for years that way.
+ */
 export interface ConfigurationSchemaDefinition {
-    [n: string]: ConfigSlotDefinition | ConfigurationSchemaDefinition | string | number | IAnyType;
+    [n: string]: ConfigSlotDefinition | string | number | IAnyType;
 }
 export interface ConfigurationSchemaOptions<BASE_SCHEMA extends AnyConfigurationSchemaType | undefined, EXPLICIT_IDENTIFIER extends string | undefined> {
     explicitlyTyped?: boolean;
@@ -15,23 +30,143 @@ export interface ConfigurationSchemaOptions<BASE_SCHEMA extends AnyConfiguration
     extend?: (self: unknown) => any;
     preProcessSnapshot?: (snapshot: Record<string, unknown>) => Record<string, unknown>;
 }
-declare function makeConfigurationSchemaModel<DEFINITION extends ConfigurationSchemaDefinition, OPTIONS extends ConfigurationSchemaOptions<any, any>>(modelName: string, schemaDefinition: DEFINITION, options: OPTIONS): import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IModelType<Record<string, any>, {
-    setSubschema(slotName: string, data: Record<string, unknown>): Record<string, unknown> | ({
-        [x: string]: any;
-    } & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject & {
-        setSubschema(slotName: string, data: Record<string, unknown>): Record<string, unknown> | ({
-            [x: string]: any;
-        } & import("@jbrowse/mobx-state-tree/dist/internal").NonEmptyObject & any & import("@jbrowse/mobx-state-tree").IStateTreeNode<AnyConfigurationSchemaType>);
-    } & import("@jbrowse/mobx-state-tree").IStateTreeNode<AnyConfigurationSchemaType>);
+type SchemaHook = (self: unknown) => any;
+/**
+ * Options as **stored**: what a caller passes, except that the three
+ * MST-chained hooks may have accumulated a chain by merging in a
+ * `baseConfiguration`. A caller's single function is a valid chain of one, so
+ * `ConfigurationSchemaOptions` is assignable to this and no call site changes.
+ *
+ * They stay a chain rather than being folded into one function because MST is
+ * what does the chaining: `.actions()` is called once per entry, which is what
+ * puts the base's members on `self` by the time the subclass's function runs,
+ * and what lets the subclass override one by redeclaring its name. Folding to
+ * `self => ({...base(self), ...child(self)})` would give neither, and would
+ * corrupt `extend` outright (it returns `{actions, views, state}`, so a spread
+ * merge drops whichever side declared fewer of the three).
+ *
+ * `preProcessSnapshot` is the exception and composes into a single function,
+ * `child(base(snapshot))`: the base normalizes and migrates first, the subclass
+ * refines. It has to stay one function because `preProcessSlotValues` calls it
+ * straight off the registry (slotFacade.ts).
+ */
+export interface MergedConfigurationSchemaOptions<BASE_SCHEMA extends AnyConfigurationSchemaType | undefined, EXPLICIT_IDENTIFIER extends string | undefined> extends Omit<ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER>, 'actions' | 'views' | 'extend'> {
+    actions?: SchemaHook | SchemaHook[];
+    views?: SchemaHook | SchemaHook[];
+    extend?: SchemaHook | SchemaHook[];
+}
+declare function makeConfigurationSchemaModel<DEFINITION extends ConfigurationSchemaDefinition, OPTIONS extends MergedConfigurationSchemaOptions<any, any>>(modelName: string, schemaDefinition: DEFINITION, options: OPTIONS): import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IModelType<Record<string, any>, {
+    setSubschema(slotName: string, data: Record<string, unknown>): any;
+    setSlot(slotName: string, value: unknown): void;
 }, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>, [undefined]>;
 export interface ConfigurationSchemaType<DEFINITION extends ConfigurationSchemaDefinition, OPTIONS extends ConfigurationSchemaOptions<any, any>> extends ReturnType<typeof makeConfigurationSchemaModel<DEFINITION, OPTIONS>> {
-    isJBrowseConfigurationSchema: boolean;
-    jbrowseSchemaDefinition: DEFINITION;
-    jbrowseSchemaOptions: OPTIONS;
     type: string;
-    [key: string]: unknown;
 }
-export declare function ConfigurationSchema<DEFINITION extends ConfigurationSchemaDefinition, OPTIONS extends ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER>, BASE_SCHEMA extends AnyConfigurationSchemaType | undefined = undefined, EXPLICIT_IDENTIFIER extends string | undefined = undefined>(modelName: string, inputSchemaDefinition: DEFINITION, inputOptions?: ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER>): ConfigurationSchemaType<DEFINITION, OPTIONS>;
-export declare function TrackConfigurationReference(schemaType: IAnyType): import("@jbrowse/mobx-state-tree").ISnapshotProcessor<import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, any>, import("@jbrowse/mobx-state-tree")._NotCustomized, any>;
+export declare function ConfigurationSchema<const DEFINITION extends ConfigurationSchemaDefinition, BASE_SCHEMA extends AnyConfigurationSchemaType | undefined = undefined, EXPLICIT_IDENTIFIER extends string | undefined = undefined>(modelName: string, inputSchemaDefinition: DEFINITION, inputOptions?: ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER>): ConfigurationSchemaType<DEFINITION, ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER>>;
+/**
+ * #api core/configuration
+ * Hydrate a plain track config into a live config node, dispatching on its
+ * `type` to find the schema. `session.tracks` holds `types.frozen` plain
+ * objects until something references a track (ADR-031), so a caller handed one
+ * of those has a config that reads nothing but what was literally authored: a
+ * slot at its schema default is absent, `preProcessSnapshot` has not run, and
+ * nothing that walks a live node — the promotable cascade above all — applies
+ * to it.
+ *
+ * For the callers that need the resolved answer rather than the authored one
+ * and cannot know which of the two they were handed. The About dialog's "Copy
+ * config" is the case this exists for: it is reached from two menus, and one of
+ * them passes a `session.tracks` entry.
+ *
+ * Returns **undefined** rather than throwing when the config names a track type
+ * no plugin registered, or when it is invalid enough that `create` rejects it —
+ * an un-hydrated config has never been validated, so a dialog that opens over
+ * it must not be the thing that discovers this. Callers fall back to treating
+ * it as the plain object it is.
+ *
+ * Shares `TrackConfigurationReference`'s per-PluginManager cache, so hydrating
+ * the same entry twice returns the same node and a track that gets opened later
+ * reuses it.
+ */
+export declare function hydrateTrackConfig(pluginManager: PluginManager, config: Record<string, unknown>): AnyConfigurationModel | undefined;
+/**
+ * Reference to a track configuration. Snapshot output is the trackId string.
+ *
+ * One load-bearing complication: **`types.union(trackRef, schemaType)` accepts a
+ * string id OR a full config.** A view that synthesizes a track nobody else can
+ * draw — a read-vs-ref synteny band, an SV inspector row, a circular view's
+ * added track — writes the config here rather than registering it in
+ * `session.tracks`, and it then lives and dies with the track that holds it.
+ * `ReadVsRef.test.tsx` and `SVInspector.test.tsx` are the canaries.
+ *
+ * NOTE: don't add `as SCHEMATYPE` to the return value. It narrows SnapshotIn
+ * to just the object branch, forcing callers to wrap string ids in
+ * `@ts-expect-error`. The inferred union SnapshotIn is `string | SnapshotIn<schema>`.
+ */
+export declare function TrackConfigurationReference(schemaType: IAnyType): import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, any>;
+/**
+ * Reference to a display configuration. Looked up inside the containing track
+ * config's `displays` array. Snapshot output is the displayId string.
+ *
+ * Resolution order:
+ *   1. by displayId
+ *   2. by `parent.type` — handles old sessions where the saved displayId
+ *      no longer matches but a display of the same type exists on the track
+ *
+ * Step 2 is the safety net because `baseTrackConfig.preProcessSnapshot`
+ * already injects a stub display for every registered displayType on the
+ * track, so a same-type lookup always succeeds at runtime for properly
+ * loaded tracks. An older third step auto-created a *detached* config when
+ * neither matched — that produced an orphaned MST node whose edits silently
+ * didn't persist. Removed in favor of a clear throw, since
+ * preProcessSnapshot's injection makes the path effectively dead.
+ *
+ * Union-with-schemaType branch is for the same reason as `TrackConfigurationReference`:
+ * `CircularView.addTrackConf` passes inline display configs as MST instances.
+ */
 export declare function DisplayConfigurationReference(schemaType: IAnyType): import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, any>;
-export declare function ConfigurationReference<SCHEMATYPE extends AnyConfigurationSchemaType>(schemaType: SCHEMATYPE): SCHEMATYPE;
+type ConfigReferenceInstance<SCHEMA extends AnyConfigurationSchemaType> = (SCHEMA extends ConfigurationSchemaType<infer D, any> ? IsAny<D> extends true ? any : SCHEMA['Type'] : SCHEMA['Type']) & {
+    [K in GetInheritedIdentifier<SCHEMA>]: string;
+};
+/**
+ * Static type of the value `ConfigurationReference` produces, and therefore of a
+ * track/display state model's `configuration` prop. Its **instance** type is a
+ * clean, single-branded schema instance (see `ConfigReferenceInstance`), so
+ * `ConfigurationSchemaForModel` — and thus `getConf(self, slot)` /
+ * `readConfObject(self.configuration, slot)` — recovers the concrete schema and
+ * its precise slot value types instead of `any`. The snapshot types stay
+ * `id-string | schema-snapshot`, matching the runtime union (`idOrSnapshotUnion`):
+ * a saved config serializes to its id string, and both an id string and a full
+ * inline snapshot are accepted as input — so views that push string ids or
+ * synthesized configs (`CircularView`, `SvInspectorView`) keep type-checking.
+ *
+ * Built by `Omit`-ing `Type` off `IType` and re-adding it, rather than reusing
+ * the runtime `ITypeUnion`: `IType`'s own `Type` is `STNValue<T, this>`, which
+ * re-brands `T` with `IStateTreeNode<this>`. Layering that over an already-branded
+ * `SCHEMA['Type']` (which carries `IStateTreeNode<SCHEMA>`) double-brands the
+ * node, and the two competing `IStateTreeNode<…>` brands defeat the single
+ * `infer SCHEMA` in `ConfigurationSchemaForModel` (leaving it `any`). Re-adding a
+ * plain `Type` keeps the single brand. See the "Config read type narrowing"
+ * section of `packages/core/src/configuration/CLAUDE.md`.
+ */
+export type IConfigurationReference<SCHEMA extends AnyConfigurationSchemaType> = Omit<IType<ReferenceIdentifier | SnapshotIn<SCHEMA>, ReferenceIdentifier | SnapshotOut<SCHEMA>, ConfigReferenceInstance<SCHEMA>>, 'Type'> & {
+    readonly Type: ConfigReferenceInstance<SCHEMA>;
+};
+/**
+ * Dispatch by the schema's identifier: `trackId` → track-ref (resolves through
+ * `session.getTrackById`), `displayId` → display-ref (resolves through the
+ * parent track's displays array), anything else → plain reference.
+ *
+ * Display schemas must declare `explicitIdentifier: 'displayId'` (directly or
+ * via `baseConfiguration: baseLinearDisplayConfigSchema`, which merges its
+ * options through `preprocessConfigurationSchemaArguments`).
+ *
+ * The return is annotated `IConfigurationReference<SCHEMATYPE>` (see its doc)
+ * so `self.configuration` carries the concrete schema. The three runtime
+ * branches produce MST reference/union types over `schemaType` that are
+ * assignable to that annotation, so `return ref` needs no cast — and must not
+ * get one: a prior `as SCHEMATYPE` was dropped because it narrowed `SnapshotIn`
+ * to just the object branch and forced callers pushing string ids to
+ * `@ts-expect-error` (see `TrackConfigurationReference`'s note).
+ */
+export declare function ConfigurationReference<SCHEMATYPE extends AnyConfigurationSchemaType>(schemaType: SCHEMATYPE): IConfigurationReference<SCHEMATYPE>;