@jbrowse/core 4.2.1 → 5.0.0-beta.1

package/esm/configuration/configurationSlot.d.ts

@@ -1,33 +1,286 @@
-import type { IAnyComplexType, IAnyModelType } from '@jbrowse/mobx-state-tree';
-export interface ConfigSlotDefinition {
+import type { JexlInstance } from '../util/jexlStrings.ts';
+import type { IAnyType } from '@jbrowse/mobx-state-tree';
+declare const slotTypes: {
+    stringArray: {
+        model: import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+        fallbackDefault: never[];
+    };
+    stringArrayMap: {
+        model: import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").IArrayType<import("@jbrowse/mobx-state-tree").ISimpleType<string>>>;
+        fallbackDefault: {};
+    };
+    numberMap: {
+        model: import("@jbrowse/mobx-state-tree").IMapType<import("@jbrowse/mobx-state-tree").ISimpleType<number>>;
+        fallbackDefault: {};
+    };
+    boolean: {
+        model: import("@jbrowse/mobx-state-tree").ISimpleType<boolean>;
+        fallbackDefault: boolean;
+    };
+    color: {
+        model: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        fallbackDefault: string;
+    };
+    integer: {
+        model: import("@jbrowse/mobx-state-tree").ISimpleType<number>;
+        fallbackDefault: number;
+    };
+    number: {
+        model: import("@jbrowse/mobx-state-tree").ISimpleType<number>;
+        fallbackDefault: number;
+    };
+    maybeNumber: {
+        model: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<number>>;
+    };
+    maybeBoolean: {
+        model: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<boolean>>;
+    };
+    maybeColor: {
+        model: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+    };
+    maybeFrozen: {
+        model: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IType<any, any, any>>;
+    };
+    string: {
+        model: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        fallbackDefault: string;
+    };
+    text: {
+        model: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        fallbackDefault: string;
+    };
+    fileLocation: {
+        model: import("@jbrowse/mobx-state-tree").ISnapshotProcessor<import("@jbrowse/mobx-state-tree").ITypeUnion<import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "LocalPathLocation";
+            localPath: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "BlobLocation";
+            name: string;
+            blobId: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "FileHandleLocation";
+            name: string;
+            handleId: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "UriLocation";
+            uri: string;
+            baseUri: string | undefined;
+            internetAccountId: string | undefined;
+            internetAccountPreAuthorization: import("@jbrowse/mobx-state-tree").ModelCreationType<{
+                internetAccountType: string;
+                authInfo: any;
+            }> | undefined;
+        }>, import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"LocalPathLocation">;
+            localPath: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        }> | import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"BlobLocation">;
+            name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            blobId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        }> | import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"FileHandleLocation">;
+            name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            handleId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        }> | {
+            locationType: "UriLocation";
+            uri: string;
+            internetAccountId: string | undefined;
+            internetAccountPreAuthorization: import("@jbrowse/mobx-state-tree").ModelSnapshotType<{
+                internetAccountType: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+                authInfo: import("@jbrowse/mobx-state-tree").IType<any, any, any>;
+            }> | undefined;
+        }, import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"LocalPathLocation">;
+            localPath: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        }> | import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"BlobLocation">;
+            name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            blobId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        }> | import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"FileHandleLocation">;
+            name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            handleId: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+        }> | import("@jbrowse/mobx-state-tree").ModelInstanceTypeProps<{
+            locationType: import("@jbrowse/mobx-state-tree").ILiteralType<"UriLocation">;
+            uri: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+            baseUri: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+            internetAccountId: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").ISimpleType<string>>;
+            internetAccountPreAuthorization: import("@jbrowse/mobx-state-tree").IMaybe<import("@jbrowse/mobx-state-tree").IModelType<{
+                internetAccountType: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
+                authInfo: import("@jbrowse/mobx-state-tree").IType<any, any, any>;
+            }, {}, import("@jbrowse/mobx-state-tree")._NotCustomized, import("@jbrowse/mobx-state-tree")._NotCustomized>>;
+        }>>, import("../util/types/mst.ts").LegacyFileLocation | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "LocalPathLocation";
+            localPath: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "BlobLocation";
+            name: string;
+            blobId: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "FileHandleLocation";
+            name: string;
+            handleId: string;
+        }> | import("@jbrowse/mobx-state-tree").ModelCreationType<{
+            locationType: "UriLocation";
+            uri: string;
+            baseUri: string | undefined;
+            internetAccountId: string | undefined;
+            internetAccountPreAuthorization: import("@jbrowse/mobx-state-tree").ModelCreationType<{
+                internetAccountType: string;
+                authInfo: any;
+            }> | undefined;
+        }>, import("@jbrowse/mobx-state-tree")._NotCustomized>;
+        fallbackDefault: {
+            uri: string;
+            locationType: string;
+        };
+    };
+    frozen: {
+        model: import("@jbrowse/mobx-state-tree").IType<any, any, any>;
+        fallbackDefault: {};
+    };
+};
+/**
+ * The builtin table's own names — every slot type whose MST model this module
+ * supplies, so excluding the two enum types. Exported for `SlotValueByType` in
+ * `types.ts`, which has to name the same set and is checked against this.
+ */
+export type BuiltinSlotTypeName = keyof typeof slotTypes;
+declare const ENUM_SLOT_TYPES: readonly ['stringEnum', 'maybeStringEnum'];
+/**
+ * Every legal `type` on a slot definition: the builtin table's own names, plus
+ * the two enum types.
+ *
+ * Closed on purpose. A name outside this set still *works* at runtime as long
+ * as a `model` is given — which is exactly the trap: the value round-trips
+ * fine, and the only symptom is that everything keyed off the type name stops
+ * recognising the slot (`slotFacade` hands the editor no `choices`, so an enum
+ * renders as a free text box).
+ */
+export type ConfigSlotType = keyof typeof slotTypes | (typeof ENUM_SLOT_TYPES)[number];
+/**
+ * The same set as `MAYBE_TYPES`, at the type level, and derived from the same
+ * property of the same table so the two cannot disagree: an entry with no
+ * `fallbackDefault` is one whose fixed form is "unset".
+ */
+type MaybeBuiltinSlotTypeName = {
+    [K in keyof typeof slotTypes]: 'fallbackDefault' extends keyof (typeof slotTypes)[K] ? never : K;
+}[keyof typeof slotTypes];
+export type MaybeSlotTypeName = MaybeBuiltinSlotTypeName | 'maybeStringEnum';
+interface ConfigSlotDefinitionCommon {
+    /** human-readable description of the slot's meaning */
     description?: string;
-    model?: IAnyModelType | IAnyComplexType;
-    type: string;
-    defaultValue: any;
+    /** custom base MST model for the slot's value */
+    model?: IAnyType;
+    /** parameter names of the function callback */
     contextVariable?: string[];
+    /**
+     * hide this slot behind a "Show advanced settings" toggle in the config
+     * editor, so common slots aren't crowded out by rarely-changed ones
+     */
+    advanced?: boolean;
+    /**
+     * **Declaring this makes the slot promotable**, and it is the only thing that
+     * does: a user can promote the slot's value to a session-wide default for all
+     * tracks of the same display type (the track-menu pin). An *unset* slot
+     * follows (inherits) that promoted default; any concrete value customizes the
+     * track. Read it with `resolveConf`, never `getConf`; see
+     * `promotableResolve.ts`.
+     *
+     * The value itself is what the unset state resolves to when a track inherits
+     * and nothing is promoted. This is the CSS model — being unset is the
+     * `inherit` keyword and `promotedBase` is `initial` (the value at the bottom
+     * of the cascade). Spending only `undefined` on the sentinel is what leaves
+     * every *real* value — `promotedBase` included — customizable over an opposite
+     * session default, so a track can hold `displayMode: 'normal'` under a
+     * promoted `'compact'`.
+     *
+     * Requires a `maybe*` slot type (whose `undefined` is the inherit sentinel)
+     * and no `defaultValue`; `ConfigSlot` throws otherwise, and both stay runtime
+     * checks. Forbidding it on the plain half of `ConfigSlotDefinition` was tried:
+     * it forces a cast into `mergeSchemaDefinition`, whose spread of two slot
+     * definitions lands in neither member, and buys only an earlier version of a
+     * throw that already fires when the schema is built.
+     *
+     * A subclass turns an inherited promotable slot back into a plain one by
+     * stating `promotedBase: undefined` — the definition merge is a spread, so a
+     * stated `undefined` really does overwrite the base's value.
+     */
+    promotedBase?: unknown;
+    /**
+     * For a promotable slot: an extra semantic check a stored value must pass,
+     * on top of the built-in type-shape check, before the cascade
+     * (`promotableResolve.ts`'s `isUsableValue`) treats it as usable. Applies to
+     * both cascade tiers — a session-wide promoted default and a track's own saved
+     * value. Needed when a slot's shape alone can't catch a semantically-invalid
+     * value — e.g. alignments `colorBy`'s `.type` must name a currently-registered
+     * color scheme, not just be *some* string — so a stale scheme name (renamed or
+     * removed since the value was saved) degrades to "not usable" (falls back to
+     * the base) instead of reaching a lookup that assumes every `.type` is
+     * registered. Omit when the type-shape check alone is enough to trust the value.
+     *
+     * Runs at **schema build** too, over the slot's own `promotedBase` — the base
+     * is what every failing tier degrades to, so it has to clear the same bar.
+     * Keep the hook a function of module-level data (as `isRegisteredColorScheme`
+     * is of `COLOR_SCHEMES`); one that consults state its plugin registers later
+     * during `install()` would reject a base that is really fine.
+     */
+    validate?: (value: unknown) => boolean;
 }
-export default function ConfigSlot(slotName: string, { description, model, type, defaultValue, contextVariable, }: ConfigSlotDefinition): import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").IModelType<{
-    name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    description: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    type: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    value: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, any>, [undefined]>;
-}, {
-    contextVariable: string[];
-} & {
-    readonly isCallback: boolean;
-} & {
-    readonly expr: any;
-    readonly valueJSON: any[] | Record<string, any> | string | undefined;
-} & {
-    getValue(args?: Record<string, unknown>): any;
-} & {
-    set(newVal: any): void;
-    reset(): void;
-    convertToCallback(): void;
-    convertToValue(): void;
-}, import("@jbrowse/mobx-state-tree").ModelCreationType<import("@jbrowse/mobx-state-tree/dist/internal").ExtractCFromProps<{
-    name: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    description: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    type: import("@jbrowse/mobx-state-tree").ISimpleType<string>;
-    value: import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, any>, [undefined]>;
-}>>, any>, [undefined]>;
+/**
+ * A slot definition, split on whether the slot's type spends `undefined` on
+ * "unset". The type-level twin of `ConfigSlot`'s
+ * `defaultValue === undefined && !MAYBE_TYPES.has(type)` throw, which used to be
+ * the only statement of the rule: a `maybe*` slot has exactly one legal
+ * `defaultValue`, so requiring the field of every slot alike made 81 slots
+ * across the repo carry a `defaultValue: undefined` line that said nothing.
+ *
+ * A `maybe*` slot's only legal `defaultValue` is the sentinel itself, but the
+ * field stays `unknown` rather than being pinned to `undefined`: the spread in
+ * `mergeSchemaDefinition` combines a base and a child whose halves may disagree,
+ * so pinning it forces a cast through the one place slot definitions are
+ * combined. `ConfigSlot` throws on a concrete one instead — and has to anyway,
+ * since no type can see what a `baseConfiguration` merged in, which is the way
+ * this mistake actually happens.
+ *
+ * Stating the sentinel stays meaningful in a subclass override, where the merge
+ * is a spread and an omitted key inherits the base's value.
+ */
+export type ConfigSlotDefinition = (ConfigSlotDefinitionCommon & {
+    /** a `maybe*` slot type, whose unset state is `undefined` */
+    type: MaybeSlotTypeName;
+    /** optional: unset is the default, and the only value `ConfigSlot` accepts */
+    defaultValue?: unknown;
+}) | (ConfigSlotDefinitionCommon & {
+    /** name of the type of slot, e.g. "string", "number", "stringArray" */
+    type: Exclude<ConfigSlotType, MaybeSlotTypeName>;
+    /** default value of the slot; required, since no other value means "unset" */
+    defaultValue: unknown;
+});
+/**
+ * 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`.
+ */
+export default function ConfigSlot(definition: ConfigSlotDefinition): import("@jbrowse/mobx-state-tree").IOptionalIType<import("@jbrowse/mobx-state-tree").ITypeUnion<any, any, any>, [undefined]>;
+/**
+ * New value when converting a fixed-value slot to a jexl callback. Already-
+ * callback values are returned unchanged.
+ *
+ * A single JSON.stringify covers every type: `jexl:${42}` and
+ * `jexl:${JSON.stringify(42)}` are identical for numbers/booleans, and the rest
+ * need the quoting/serialization anyway.
+ */
+export declare function toCallbackValue(value: unknown): string;
+/**
+ * New value when converting a jexl callback back to a fixed value: try
+ * evaluating with no args, else fall back to the slot default (and to the slot
+ * type's `fallbackDefault` if the default is itself a callback).
+ */
+export declare function toFixedValue(value: unknown, type: ConfigSlotType, defaultValue: unknown, jexl: JexlInstance): unknown;
+export {};