@jbrowse/core 5.0.0-beta.10 → 5.0.0-beta.13

package/esm/configuration/plot.js

@@ -0,0 +1,175 @@
+import { getSnapshot, getType, isArrayType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+import { compareStructural } from 'mobx';
+import { colorProblems, colorSlotsOf, noticeLines, scaleEndProblems, scaleEndsOf, } from '../util/colorScale.js';
+import { readConfObject } from './readConfObject.js';
+import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
+import { bareFormOf, shorthandTargets } from './schemaTypes.js';
+/**
+ * #api core/configuration
+ * The grammar's settings, by the slot name every display that has one gives
+ * it, and what each holds: what "Edit plot..." shows and an agent reads as a
+ * display's `plot`. A display's plot is the ones its config declares
+ * (`plotKeysOf`).
+ */
+export const PLOT_VOCABULARY = {
+    marks: 'the marks drawn in order, each a mark and an encoding',
+    transform: 'the steps run over the features before any mark',
+    unit: 'what one row stands for: a read or a chain, a sample or a haplotype',
+    facet: 'one section per value of a field',
+    rows: 'the rows: their field or order, labels, focus and tree',
+    rowColor: 'the colour of each row, by a row attribute',
+    color: 'the colour',
+    baseColor: 'the per-base layer over the reads',
+    arcColor: 'the colour of the arcs between mates',
+    ribbonColor: 'the colour of the ribbons between lanes',
+    laneLayers: 'the layers drawn over each lane',
+    scales: 'the axes, scales.y the value axis',
+    y: "what each row's bar height carries",
+    filter: 'the jexl: expressions a feature has to pass',
+    filterBy: 'the read flags and tags a read has to pass',
+};
+const LIFT_ID = 'plotLift';
+/**
+ * #api core/configuration
+ * The plot keys a display config declares.
+ */
+export function plotKeysOf(conf) {
+    const definition = getConfigurationSchemaMetadata(conf)?.definition ?? {};
+    return Object.keys(PLOT_VOCABULARY).filter(key => Object.hasOwn(definition, key));
+}
+// A one-member object a shorthand would write as a bare value prints as that
+// value, as a config file writes it: `color: "red"`, `facet: "strand"`.
+function folded(member, value) {
+    if (!isStateTreeNode(member) ||
+        typeof value !== 'object' ||
+        value === null ||
+        Array.isArray(value)) {
+        return value;
+    }
+    const meta = getConfigurationSchemaMetadata(member);
+    const entries = Object.entries(value);
+    if (!meta || meta.options.shorthandWith || entries.length !== 1) {
+        return value;
+    }
+    const [slot, bare] = entries[0];
+    const form = bareFormOf(bare);
+    return form && shorthandTargets(meta)[form] === slot ? bare : value;
+}
+/**
+ * #api core/configuration
+ * A display's plot as declared, defaults left off. A list sitting at a
+ * default it shares with no other display, a default plot's marks, shows its
+ * entries, since they are what is drawn.
+ */
+export function plotOf(conf) {
+    const snapshot = getSnapshot(conf);
+    const plot = {};
+    for (const key of plotKeysOf(conf)) {
+        const member = conf[key];
+        const value = snapshot[key] ??
+            (isStateTreeNode(member) &&
+                isArrayType(getType(member)) &&
+                member.length > 0
+                ? getSnapshot(member)
+                : undefined);
+        if (value !== undefined) {
+            plot[key] = folded(member, value);
+        }
+    }
+    return plot;
+}
+function checkKeys(draft, keys) {
+    const unknown = Object.keys(draft).filter(key => !keys.includes(key));
+    if (unknown.length > 0) {
+        throw new Error(`This display's plot is ${keys.join(', ')}, not ${unknown.join(', ')}`);
+    }
+}
+/**
+ * #api core/configuration
+ * The text as a plot, refusing a key the display's plot does not hold. The
+ * schema is the parser past this point.
+ */
+export function parsePlot(text, keys) {
+    const parsed = JSON.parse(text);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`A plot is one JSON object of ${keys.join(', ')}`);
+    }
+    checkKeys(parsed, keys);
+    return parsed;
+}
+function merged(draft, current) {
+    const out = { ...current };
+    for (const [key, value] of Object.entries(draft)) {
+        if (value === null) {
+            delete out[key];
+        }
+        else if (value !== undefined) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * #api core/configuration
+ * A draft as the display's config would hold it, through the schema's own
+ * lift and checks: a shorthand becomes its object, a default falls off, and
+ * what a config file is refused for throws, a key outside the plot included.
+ * The node is never attached, so nothing on the display is touched; a display
+ * reads its typed members off it. The draft is copied first, since MST
+ * freezes what it creates from.
+ */
+export function liftPlot(conf, draft) {
+    checkKeys(draft, plotKeysOf(conf));
+    return getType(conf).create({
+        displayId: LIFT_ID,
+        ...structuredClone(merged(draft, plotOf(conf))),
+    });
+}
+/**
+ * #api core/configuration
+ * What applying a draft writes: each setting whose lifted value differs from
+ * the plot, as the lifted value, and `null` for one it resets. A value
+ * spelled another way but lifting to the same setting writes nothing.
+ * Throws a refusal before anything is written.
+ */
+export function plotWrites(conf, draft) {
+    const current = plotOf(conf);
+    const lifted = plotOf(liftPlot(conf, draft));
+    const writes = {};
+    for (const [key, value] of Object.entries(draft)) {
+        if (value === undefined || compareStructural(lifted[key], current[key])) {
+            continue;
+        }
+        writes[key] = lifted[key] ?? null;
+    }
+    return writes;
+}
+function subConfOf(conf, key) {
+    const member = conf[key];
+    return isStateTreeNode(member) ? member : undefined;
+}
+function membersOf(node) {
+    return (name) => readConfObject(node, name);
+}
+/**
+ * What a lifted plot's colour objects and `scales.y` say together that the
+ * display cannot draw as written, as corner-notice lines: each colour object
+ * under its schema's `fieldPresets`, as `jbrowse validate` judges it.
+ */
+export function schemaPlotProblems(lifted) {
+    return plotKeysOf(lifted).flatMap(key => {
+        const node = subConfOf(lifted, key);
+        const presets = node
+            ? getConfigurationSchemaMetadata(node)?.options.fieldPresets
+            : undefined;
+        const y = key === 'scales' && node ? subConfOf(node, 'y') : undefined;
+        return [
+            ...(node && presets
+                ? noticeLines(key, colorProblems(colorSlotsOf(membersOf(node)), presets))
+                : []),
+            ...(y
+                ? noticeLines('scales.y', scaleEndProblems(scaleEndsOf(membersOf(y))))
+                : []),
+        ];
+    });
+}

package/esm/configuration/readConfObject.d.ts

@@ -3,20 +3,13 @@ import type { JexlInstance } from '../util/jexlStrings.ts';
 import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue } from './types.ts';
 /**
  * #api core/configuration
- * Given a configuration model (an instance of a ConfigurationSchema), read the
- * configuration value at the given path. Use this when you hold the
- * configuration model directly, e.g. an entry from `session.tracks`.
+ * Read the value at a path of a live config node, such as a track's
+ * `configuration`, evaluating a `jexl:` callback with `args`.
  *
- * Wants a **live config node**, not a snapshot of one, and passing a snapshot is
- * a type error. Slots are built with `types.stripDefault`, so a slot sitting at
- * its default is absent from a snapshot — "unset" and "at its default" are
- * indistinguishable there, and a read off one reports a default as missing.
- *
- * That is enforced in the types only, deliberately: it can't be a runtime check.
- * `generateHierarchy` reads slots straight off the **un-hydrated frozen** entries
- * of `jbrowse.tracks` on purpose, because hydrating every track to answer the
- * track selector is what `types.frozen` exists to avoid — and those reads are
- * indistinguishable at runtime from the broken spelling.
+ * A snapshot is refused by the types, since a slot at its default is absent
+ * from one. A `session.tracks` entry is one (`TrackConfigEntry`): read its
+ * `trackId` and `type` directly, and a slot through a helper that supplies the
+ * default, such as `getConfAssemblyNamesOrNone`.
  *
  * @param model - instance of ConfigurationSchema
  * @param slotPaths - array of paths to read
@@ -26,9 +19,14 @@ import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSche
 export declare function readConfObject(confObject: AnyConfigurationModel): AnyConfigurationSnapshot;
 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>;
 /**
- * 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.
+ * Read a value from a plain config snapshot, evaluating a `jexl:` callback
+ * against `feature`. For rendering code and workers; pass the realm's
+ * `pluginManager.jexl` so plugin-registered functions resolve.
  */
 export declare function readConfigValue<T>(config: Record<string, unknown>, key: string | string[], feature: Feature, jexl: JexlInstance): T;
+/**
+ * #api core/configuration
+ * A config value as `feature` reads it: a `jexl:` callback evaluated against
+ * the feature, anything else as written.
+ */
+export declare function evaluateForFeature(value: unknown, feature: Feature, jexl: JexlInstance): unknown;

package/esm/configuration/readConfObject.js

@@ -1,27 +1,14 @@
 /**
  * @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.
+ * The config readers: `readConfObject` off a live config node, whose env
+ * supplies the jexl instance, and `readConfigValue` off a plain snapshot in a
+ * worker or renderer, which is handed one.
  */
 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)
@@ -35,11 +22,7 @@ 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;
@@ -47,42 +30,25 @@ function readSlot(confObject, slotName, args) {
     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.
+    // the live snapshot, stable across reads so downstream computeds memoize;
+    // 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`.
+// No looser overload admits the model: a catch-all lets a slot-name typo
+// compile 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]];
@@ -93,9 +59,6 @@ export function readConfObject(confObject, slotPath, args = {}) {
     }
     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;
@@ -107,12 +70,18 @@ function resolveConfigValue(config, key) {
     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.
+ * Read a value from a plain config snapshot, evaluating a `jexl:` callback
+ * against `feature`. For rendering code and workers; pass the realm's
+ * `pluginManager.jexl` so plugin-registered functions resolve.
  */
 export function readConfigValue(config, key, feature, jexl) {
-    const raw = resolveConfigValue(config, key);
-    return (isCallbackValue(raw) ? evaluateJexl(raw, { feature }, jexl) : raw);
+    return evaluateForFeature(resolveConfigValue(config, key), feature, jexl);
+}
+/**
+ * #api core/configuration
+ * A config value as `feature` reads it: a `jexl:` callback evaluated against
+ * the feature, anything else as written.
+ */
+export function evaluateForFeature(value, feature, jexl) {
+    return isCallbackValue(value) ? evaluateJexl(value, { feature }, jexl) : value;
 }

package/esm/configuration/schemaTypes.js

@@ -67,7 +67,11 @@ export function isSlotDefinitionEntry(def) {
 export function isConfigurationModel(thing) {
     return isStateTreeNode(thing) && isConfigurationSchemaType(getType(thing));
 }
-const NUMBER_SLOT_TYPES = new Set(['number', 'integer', 'maybeNumber']);
+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

package/esm/configuration/snapshotPreprocess.js

@@ -1,4 +1,5 @@
 import { isJexl } from '../util/jexlStrings.js';
+import { isPlainObject } from '../util/objectUtils.js';
 import { slotWriteRefusal } from './configurationSlot.js';
 import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
 import { bareFormOf, isConstantEntry, shorthandTargets } from './schemaTypes.js';
@@ -60,9 +61,6 @@ function isOwnSnapshot({ name, options }, snapshot) {
         snapshot.type === undefined ||
         snapshot.type === name);
 }
-function isPlainObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 // `lifted` under `written`: what the snapshot spells wins, member by member
 // where both are objects.
 function underWritten(written, lifted) {