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

package/esm/configuration/configurationSchema.d.ts

@@ -1,8 +1,9 @@
 import type PluginManager from '../PluginManager.ts';
 import type { IsAny } from '../util/types/isAny.ts';
 import type { ConfigSlotDefinition } from './configurationSlot.ts';
-import type { AnyConfigurationModel, AnyConfigurationSchemaType, GetInheritedIdentifier } from './types.ts';
-import type { IAnyType, IType, ReferenceIdentifier, SnapshotIn, SnapshotOut } from '@jbrowse/mobx-state-tree';
+import type { ConfigurationSchemaRequirement } from './requirements.ts';
+import type { AnyConfigurationModel, AnyConfigurationSchemaType, ConfigNodeActions, ConfigNodeBrand, ConfigNodeProps, IdentifierSlotDef, MergeConfigDef, TypeSlotDef } from './types.ts';
+import type { IAnyType, ISimpleType, IType, ReferenceIdentifier, SnapshotIn, SnapshotOut } from '@jbrowse/mobx-state-tree';
 export type { AnyConfigurationModel, AnyConfigurationSchemaType, } from './types.ts';
 /**
  * The three entry kinds `makeConfigurationSchemaModel` classifies: a slot
@@ -20,17 +21,57 @@ export type { AnyConfigurationModel, AnyConfigurationSchemaType, } from './types
 export interface ConfigurationSchemaDefinition {
     [n: string]: ConfigSlotDefinition | string | number | IAnyType;
 }
-export interface ConfigurationSchemaOptions<BASE_SCHEMA extends AnyConfigurationSchemaType | undefined, EXPLICIT_IDENTIFIER extends string | undefined> {
-    explicitlyTyped?: boolean;
+export type RetiredSpelling = (value: unknown) => Record<string, unknown>;
+export interface ConfigurationSchemaOptions<BASE_SCHEMA extends AnyConfigurationSchemaType | undefined, EXPLICIT_IDENTIFIER extends string | undefined, EXPLICITLY_TYPED extends boolean | undefined = boolean | undefined, REQUIREMENT extends ConfigurationSchemaRequirement = ConfigurationSchemaRequirement, SELF = any> {
+    explicitlyTyped?: EXPLICITLY_TYPED;
     explicitIdentifier?: EXPLICIT_IDENTIFIER;
-    implicitIdentifier?: string | boolean;
     baseConfiguration?: BASE_SCHEMA;
-    actions?: (self: unknown) => any;
-    views?: (self: unknown) => any;
-    extend?: (self: unknown) => any;
+    actions?: (self: SELF) => any;
+    views?: (self: SELF) => any;
+    extend?: (self: SELF) => any;
+    /**
+     * The slot a bare string or number snapshot lifts into, as that slot's type
+     * takes it, so `color: "red"` and `color: { value: "red" }` are one config,
+     * and `rules: [5]` is `rules: [{ value: 5 }]`; or two slots, one taking a
+     * number and one a string, so a width's `size: 3` is `{ value: 3 }` and
+     * `size: "score"` is `{ field: "score" }`. Applied before
+     * `preProcessSnapshot`, on every path a snapshot arrives by; the JSON schema,
+     * `describeSlots` and the config editor read it here.
+     */
+    shorthand?: string | readonly string[];
+    /**
+     * Slots a bare value sets beside `shorthand`, for a schema whose defaults
+     * would hide it: LGVSyntenyColor's `field` defaults to `strand`, so its
+     * `color: "steelblue"` is `{ value: "steelblue", scale: "none" }`.
+     */
+    shorthandWith?: Record<string, unknown>;
+    /**
+     * Refuse a snapshot key the schema does not declare, where MST would drop
+     * it in silence. Checked after the `shorthand` lift and before
+     * `preProcessSnapshot`, on the same paths.
+     */
+    closed?: boolean;
+    /**
+     * The spellings an older release used, by the name it used, each answering
+     * the members that name's value becomes. Lifted
+     * before the `closed` check and `preProcessSnapshot`, on every path a
+     * snapshot or a settings bag arrives by, and read by the `displayDefaults`
+     * router, so one declaration serves a config entry, the shorthand object, a
+     * share link and an agent's bag alike. A spelling the snapshot already
+     * carries wins over the one a lift produces.
+     */
+    retired?: Record<string, RetiredSpelling>;
+    /**
+     * A colour object's defaults by `field`, `*` for any other: the scale while
+     * `scale` is unset, and the members that scale reads while unwritten.
+     */
+    fieldPresets?: Readonly<Record<string, {
+        readonly scale: string;
+    }>>;
     preProcessSnapshot?: (snapshot: Record<string, unknown>) => Record<string, unknown>;
+    requires?: REQUIREMENT[];
 }
-type SchemaHook = (self: unknown) => any;
+type SchemaHook = (self: any) => any;
 /**
  * Options as **stored**: what a caller passes, except that the three
  * MST-chained hooks may have accumulated a chain by merging in a
@@ -47,87 +88,76 @@ type SchemaHook = (self: unknown) => any;
  *
  * `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).
+ * refines. It has to stay one function because `preProcessSnapshotWith` runs it
+ * straight off the registry, over a partial settings bag as well as a snapshot.
  */
 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>> {
-    type: string;
+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>, ConfigNodeActions, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>, [undefined]>;
+/**
+ * DEFINITION is unconstrained on purpose. It carries the *merged* definition —
+ * `MergeConfigDef`, an unresolved conditional that cannot be checked against a
+ * constraint — and intersecting it with `ConfigurationSchemaDefinition` to
+ * satisfy one would put an index signature straight back into
+ * `keyof DEFINITION`. The authoring check lives on `ConfigurationSchema`'s own
+ * parameter, where the literal arrives, and on the `extends` clause below.
+ */
+export interface ConfigurationSchemaType<out DEFINITION, OPTIONS extends ConfigurationSchemaOptions<any, any>> extends ReturnType<typeof makeConfigurationSchemaModel<DEFINITION & ConfigurationSchemaDefinition, OPTIONS>> {
+    /**
+     * Overrides the factory's, whose props come off a `Record<string, any>` and
+     * so admit every name. Slots come from the definition — the identifier and
+     * an `explicitlyTyped` schema's `type` ride in as two of them — and the brand
+     * names this schema, which is what `ConfigurationSchemaForModel` infers back
+     * out. `TypeWithoutSTN` too, since a wrapper — `types.optional`,
+     * `types.stripDefault` — builds its instance from that one.
+     */
+    readonly Type: ConfigNodeProps<DEFINITION> & ConfigNodeActions & ConfigNodeBrand<this>;
+    readonly TypeWithoutSTN: ConfigNodeProps<DEFINITION> & ConfigNodeActions;
 }
-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>>;
+type RequirementPath<D> = {
+    [K in keyof D & string]: K | (D[K] extends ConfigurationSchemaType<infer SUB, any> ? `${K}.${RequirementPath<SUB>}` : never);
+}[keyof D & string];
+type RequirementWhen<D> = {
+    [K in keyof D & string as D[K] extends {
+        type: string;
+    } ? K : never]?: (D[K] extends {
+        model: ISimpleType<infer V extends string>;
+    } ? V : string)[];
+};
+type RequirementOf<D, BASE> = BASE extends ConfigurationSchemaType<infer BD, any> ? ConfigurationSchemaRequirement<RequirementWhen<D> & RequirementWhen<BD>, RequirementPath<D> | RequirementPath<BD>> : ConfigurationSchemaRequirement<RequirementWhen<D>, RequirementPath<D>>;
+export declare function ConfigurationSchema<const DEFINITION extends ConfigurationSchemaDefinition, BASE_SCHEMA extends AnyConfigurationSchemaType | undefined = undefined, EXPLICIT_IDENTIFIER extends string | undefined = undefined, EXPLICITLY_TYPED extends boolean | undefined = undefined>(modelName: string, inputSchemaDefinition: DEFINITION, inputOptions?: ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER, EXPLICITLY_TYPED, RequirementOf<NoInfer<DEFINITION>, NoInfer<BASE_SCHEMA>>, ConfigNodeProps<MergeConfigDef<NoInfer<DEFINITION>, NoInfer<BASE_SCHEMA>>> & ConfigNodeActions>): ConfigurationSchemaType<MergeConfigDef<DEFINITION & Record<EXPLICIT_IDENTIFIER & string, IdentifierSlotDef> & (EXPLICITLY_TYPED extends true ? {
+    type: TypeSlotDef;
+} : unknown), BASE_SCHEMA>, ConfigurationSchemaOptions<BASE_SCHEMA, EXPLICIT_IDENTIFIER, EXPLICITLY_TYPED>>;
 /**
  * #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
+ * objects until something references a track (ADR-031). One of those holds only
+ * what was literally authored: a slot at its schema default is absent,
+ * `preProcessSnapshot` has not run, and nothing that walks a live node 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
+ * Use it where a caller needs the resolved config and may be handed either
+ * form. The About dialog's "Copy config" 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.
+ * Returns **undefined** when the config names a track type no plugin
+ * registered, or when `create` rejects it as invalid. An un-hydrated config has
+ * never been validated, so the dialog opening over it should not throw. Callers
+ * fall back to using the plain object.
  *
  * 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.
+ * the same entry twice returns the same node, and in an admin session a track
+ * opened later resolves to that same node. A non-admin's open track
+ * resolves to the session's private working copy (ADR-032), and this function
+ * returns the pristine mirror beside it. The two have the same content;
+ * `CopyConfigEntryPoints.test.ts` tests both cases.
  */
 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>;
-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;
-};
+type ConfigReferenceInstance<SCHEMA extends AnyConfigurationSchemaType> = SCHEMA extends ConfigurationSchemaType<infer D, any> ? IsAny<D> extends true ? any : SCHEMA['Type'] : SCHEMA['Type'];
 /**
  * Static type of the value `ConfigurationReference` produces, and therefore of a
  * track/display state model's `configuration` prop. Its **instance** type is a