@jbrowse/core 4.3.0 → 5.0.0-beta.10

package/esm/configuration/formatDetailsConfigSchema.js

@@ -0,0 +1,87 @@
+import { ConfigurationSchema } from './configurationSchema.js';
+/**
+ * Levels of subfeature the `subfeatures` callback runs on when no tier sets
+ * `depth`. Applied by the reader rather than as the slot's `defaultValue`, so
+ * the slot can still read as unset and the session's value reach a track.
+ */
+export const DEFAULT_FORMAT_DETAILS_DEPTH = 2;
+/**
+ * #config FormatDetails
+ * #category root
+ * jexl callbacks that add, rewrite or hide fields in the feature-details panel.
+ * The same schema hangs off every track and off the session as
+ * `configuration.formatDetails`, which applies to every track at once. Where
+ * both are set, the callbacks merge with the track's object over the session's,
+ * so a track can override individual keys the global callback added, and the
+ * numeric slots take the track's value when the track sets one.
+ *
+ * #example
+ * On a track. The callback returns an object merged over the feature: a new key
+ * adds a row, an existing key rewrites it, and `undefined` hides it. A bare URL
+ * is turned into a link for you, so no `<a>` markup is needed:
+ * ```js
+ * {
+ *   type: 'FeatureTrack',
+ *   trackId: 'genes',
+ *   name: 'Genes',
+ *   assemblyNames: ['hg38'],
+ *   adapter: {
+ *     type: 'Gff3TabixAdapter',
+ *     uri: 'https://example.com/genes.gff.gz',
+ *   },
+ *   formatDetails: {
+ *     feature: "jexl:{ncbi:'https://www.ncbi.nlm.nih.gov/gene/?term='+feature.name, phase:undefined}",
+ *   },
+ * }
+ * ```
+ */
+export function FormatDetailsConfigSchemaFactory() {
+    return ConfigurationSchema('FormatDetails', {
+        /**
+         * #slot formatDetails.feature
+         * callback returning an object of fields to merge onto the clicked feature.
+         * `track` is the track's config, so one session-wide callback can link out
+         * per assembly or name the track. A plain object works too, for fields
+         * that are the same on every feature
+         */
+        feature: {
+            type: 'frozen',
+            description: 'adds extra fields to the feature details',
+            defaultValue: {},
+            contextVariable: ['feature', 'track'],
+        },
+        /**
+         * #slot formatDetails.subfeatures
+         * the same, applied to each subfeature down to `depth`. `parent` is the
+         * feature it sits in and `depth` how far down, 1 for a gene's transcript
+         * and 2 for the transcript's exon
+         */
+        subfeatures: {
+            type: 'frozen',
+            description: 'adds extra fields to the subfeatures of a feature',
+            defaultValue: {},
+            contextVariable: ['feature', 'parent', 'depth', 'track'],
+        },
+        /**
+         * #slot formatDetails.depth
+         * how many levels of subfeature the `subfeatures` callback runs on,
+         * defaulting to 2, which stops at a gene's transcripts rather than
+         * descending into their exons and CDSs. A track's value wins over the
+         * session's
+         */
+        depth: {
+            type: 'maybeNumber',
+            description: 'levels of subfeature the formatDetails.subfeatures callback runs on, default 2',
+        },
+        /**
+         * #slot formatDetails.maxDepth
+         * how many levels of subfeature card the panel renders at all, which is a
+         * separate question from how deep `subfeatures` formats. Unset means no
+         * limit. A track's value wins over the session's
+         */
+        maxDepth: {
+            type: 'maybeNumber',
+            description: 'hide subfeatures nested deeper than this, default no limit',
+        },
+    });
+}

package/esm/configuration/fullConfSnapshot.d.ts

@@ -0,0 +1,13 @@
+import type { AnyConfigurationModel } from './types.ts';
+/**
+ * Plain-object snapshot of a configuration model including ALL values, even
+ * defaults. Unlike `getSnapshot()`, which strips a slot sitting at its default
+ * via `types.stripDefault`, this returns every slot's current value, so the
+ * result is a self-contained config object an RPC worker can read with no
+ * schema. JEXL callback slots keep their raw `"jexl:..."` string for the worker
+ * to evaluate per-feature. A sub-schema recurses, and so does each entry of an
+ * array or map of them; an explicitly typed schema carries its `type`, which
+ * is what tells the entries of a union list apart. Constants are the editor's
+ * and are left out.
+ */
+export declare function fullConfSnapshot(confObject: AnyConfigurationModel): Record<string, unknown>;

package/esm/configuration/fullConfSnapshot.js

@@ -0,0 +1,44 @@
+import { getSnapshot, getType, isArrayType, isMapType, isStateTreeNode, } from '@jbrowse/mobx-state-tree';
+import { getConfigurationSchemaMetadata } from './schemaRegistry.js';
+import { isConfigurationSchemaType, isSlotDefinitionEntry, } from './schemaTypes.js';
+// a sub-schema member: one node, or an array or map of them, entry by entry
+function subConfSnapshot(member) {
+    if (!isStateTreeNode(member)) {
+        return member;
+    }
+    const type = getType(member);
+    if (isArrayType(type)) {
+        return member.map(fullConfSnapshot);
+    }
+    if (isMapType(type)) {
+        return Object.fromEntries([...member.entries()].map(([key, node]) => [key, fullConfSnapshot(node)]));
+    }
+    return fullConfSnapshot(member);
+}
+/**
+ * Plain-object snapshot of a configuration model including ALL values, even
+ * defaults. Unlike `getSnapshot()`, which strips a slot sitting at its default
+ * via `types.stripDefault`, this returns every slot's current value, so the
+ * result is a self-contained config object an RPC worker can read with no
+ * schema. JEXL callback slots keep their raw `"jexl:..."` string for the worker
+ * to evaluate per-feature. A sub-schema recurses, and so does each entry of an
+ * array or map of them; an explicitly typed schema carries its `type`, which
+ * is what tells the entries of a union list apart. Constants are the editor's
+ * and are left out.
+ */
+export function fullConfSnapshot(confObject) {
+    const meta = getConfigurationSchemaMetadata(getType(confObject));
+    const result = meta?.options.explicitlyTyped
+        ? { type: confObject.type }
+        : {};
+    for (const [key, def] of Object.entries(meta?.definition ?? {})) {
+        const member = confObject[key];
+        if (isSlotDefinitionEntry(def)) {
+            result[key] = isStateTreeNode(member) ? getSnapshot(member) : member;
+        }
+        else if (isConfigurationSchemaType(def) && member !== undefined) {
+            result[key] = subConfSnapshot(member);
+        }
+    }
+    return result;
+}

package/esm/configuration/getConf.d.ts

@@ -0,0 +1,92 @@
+import type { AnyConfigurationModel, AnyConfigurationSnapshot, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue } from './types.ts';
+/**
+ * #api core/configuration
+ * Reads a configuration value from a state model that has a `.configuration`
+ * member (a track or display state model). For a raw configuration model, use
+ * `readConfObject` instead.
+ *
+ * **This is exactly `readConfObject(model.configuration, path)`** — sugar for
+ * the `.configuration` hop, and nothing more. The two readers carry the same
+ * slot-name check, so reaching for the other one does not get a typo past tsc.
+ * It does not consult the session and has no per-slot behavior; what you read is
+ * what the track stores.
+ *
+ * @param model - object containing a 'configuration' member
+ * @param slotPaths - array of paths to read
+ * @param args - extra arguments e.g. for a feature callback,
+ *   will be sent to each of the slotNames
+ */
+export declare function getConf(model: {
+    configuration: AnyConfigurationModel;
+}): AnyConfigurationSnapshot;
+export declare function getConf<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(model: {
+    configuration: CONFMODEL;
+}, slotPath: SLOT, args?: Record<string, unknown>): SLOT extends string ? ConfigurationSlotValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT> : ConfigurationSlotPathValue<ConfigurationSchemaForModel<CONFMODEL>, SLOT>;
+/**
+ * #api core/configuration
+ * Write counterpart to `getConf`, and it takes the same path: a slot name, or
+ * an array naming a sub-schema's member at any depth —
+ * `setConf(self, ['scales', 'y', 'domainMin'], 5)`. Takes the display or track
+ * model, or a config node directly.
+ *
+ * **The path length says what the write replaces.** A path ending on a slot
+ * writes that slot and leaves the object around it alone; a path ending on a
+ * sub-schema replaces the whole object, which is how a channel whose members
+ * move together — a facet's field and the domain that field's values order —
+ * gets written without a stale member surviving underneath.
+ *
+ * **Prefer this over a bare `self.configuration.setSlot('x', v)`.** The
+ * constraint here mirrors `getConf`'s, so on a model with a concrete schema an
+ * unknown slot name is a compile error. `setSlot` itself stays untyped on
+ * purpose — the config editor's slot facade routes dynamic slot names through
+ * it (`configurationSchema.ts`) — and guards the name at runtime instead
+ * (ADR-052), so a misspelled write is diagnosed one way or the other.
+ *
+ * **The read is the half with no diagnostic at all.** `getConf` for a name the
+ * schema doesn't declare returns `undefined` and reports nothing, at any layer,
+ * so the slot keeps reading as its default forever. Which makes the
+ * compile-time constraint worth keeping *reachable*: it is only as good as the
+ * schema of the holder handed in, and a holder widened to
+ * `AnyConfigurationModel` switches it off entirely — the trap a mixin casting
+ * to reach its host walks into. Every such cast names a concrete schema instead
+ * (`ConfigModelForFields`, or the base schema when the slot is the base's), and
+ * `HostChecksSlotNames` pins each one.
+ *
+ * A wrong *value* type still throws at runtime (MST type-checks the assignment)
+ * rather than at compile time. `value` is deliberately `unknown` because
+ * `undefined` is a legitimate write — it resets a slot to its schema default —
+ * and the declared slot value type doesn't include it.
+ *
+ * @param target - a model with a `configuration` member, or a config node
+ * @param slotPath - the slot to write, or the path to one
+ * @param value - the new value
+ */
+export declare function setConf<CONFMODEL extends AnyConfigurationModel, const SLOT extends ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>> | ConfigurationSlotPath<ConfigurationSchemaForModel<CONFMODEL>> = ConfigurationSlotName<ConfigurationSchemaForModel<CONFMODEL>>>(target: CONFMODEL | {
+    configuration: CONFMODEL;
+}, slotPath: SLOT, value: unknown): void;
+export interface ConfSettingsReport {
+    /** the keys the config declares, written */
+    applied: string[];
+    /** the keys it does not, with the values the lift left them */
+    undeclared: Record<string, unknown>;
+    /** a declared key whose write threw, and why */
+    failed: {
+        key: string;
+        error: string;
+    }[];
+}
+/**
+ * #api core/configuration
+ * Write a settings bag — a session spec's track entry, a share link, an agent
+ * call — onto a config. Each key names a member: a slot or a channel is written
+ * whole, as `setConf` writes it, so `null` resets it (ADR-146); a namespace's
+ * object names members inside it, at any depth, and the ones it leaves out
+ * keep their values. The config's own lift and checks run over the bag first,
+ * and each namespace's over its part, so a shorthand or a legacy key reads the
+ * same here as in `config.json`. A key the config does not declare is reported
+ * for the caller to route or refuse, and a declared key whose write throws
+ * costs that key alone.
+ */
+export declare function applyConfSettings(target: AnyConfigurationModel | {
+    configuration: AnyConfigurationModel;
+}, settings: Record<string, unknown>): ConfSettingsReport;

package/esm/configuration/getConf.js

@@ -0,0 +1,141 @@
+import { getType, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import { isPlainObject } from '../util/objectUtils.js';
+import { readConfObject } from './readConfObject.js';
+import { getConfigurationSchemaDefinition, getConfigurationSchemaMetadata, } from './schemaRegistry.js';
+import { isConfigurationModel, isConfigurationSchemaType, isConstantEntry, } from './schemaTypes.js';
+import { preProcessSnapshotWith } from './snapshotPreprocess.js';
+export function getConf(model, slotPath, args = {}) {
+    return readConfObject(model.configuration, slotPath, args);
+}
+/**
+ * #api core/configuration
+ * Write counterpart to `getConf`, and it takes the same path: a slot name, or
+ * an array naming a sub-schema's member at any depth —
+ * `setConf(self, ['scales', 'y', 'domainMin'], 5)`. Takes the display or track
+ * model, or a config node directly.
+ *
+ * **The path length says what the write replaces.** A path ending on a slot
+ * writes that slot and leaves the object around it alone; a path ending on a
+ * sub-schema replaces the whole object, which is how a channel whose members
+ * move together — a facet's field and the domain that field's values order —
+ * gets written without a stale member surviving underneath.
+ *
+ * **Prefer this over a bare `self.configuration.setSlot('x', v)`.** The
+ * constraint here mirrors `getConf`'s, so on a model with a concrete schema an
+ * unknown slot name is a compile error. `setSlot` itself stays untyped on
+ * purpose — the config editor's slot facade routes dynamic slot names through
+ * it (`configurationSchema.ts`) — and guards the name at runtime instead
+ * (ADR-052), so a misspelled write is diagnosed one way or the other.
+ *
+ * **The read is the half with no diagnostic at all.** `getConf` for a name the
+ * schema doesn't declare returns `undefined` and reports nothing, at any layer,
+ * so the slot keeps reading as its default forever. Which makes the
+ * compile-time constraint worth keeping *reachable*: it is only as good as the
+ * schema of the holder handed in, and a holder widened to
+ * `AnyConfigurationModel` switches it off entirely — the trap a mixin casting
+ * to reach its host walks into. Every such cast names a concrete schema instead
+ * (`ConfigModelForFields`, or the base schema when the slot is the base's), and
+ * `HostChecksSlotNames` pins each one.
+ *
+ * A wrong *value* type still throws at runtime (MST type-checks the assignment)
+ * rather than at compile time. `value` is deliberately `unknown` because
+ * `undefined` is a legitimate write — it resets a slot to its schema default —
+ * and the declared slot value type doesn't include it.
+ *
+ * @param target - a model with a `configuration` member, or a config node
+ * @param slotPath - the slot to write, or the path to one
+ * @param value - the new value
+ */
+export function setConf(target, slotPath, value) {
+    writeConfPath(isConfigurationModel(target) ? target : target.configuration, typeof slotPath === 'string' ? [slotPath] : slotPath, value);
+}
+/**
+ * Walk to the node the last segment names a member of, then write that member
+ * through whichever of the node's two write actions the member is: a
+ * sub-schema, single or a collection, is replaced whole, and a slot goes
+ * through `setSlot` so ADR-052's name guard and the value-type guard both run.
+ * MST's `applyPatch` takes the same path and runs neither guard.
+ */
+function writeConfPath(conf, path, value) {
+    if (!path.length) {
+        throw new Error('setConf needs a slot name or a path to one');
+    }
+    let node = conf;
+    for (const segment of path.slice(0, -1)) {
+        const child = node[segment];
+        if (!isConfigurationModel(child)) {
+            throw new Error(`${getType(node).name} has no sub-schema "${segment}", so ${path.join('.')} names nothing to write`);
+        }
+        node = child;
+    }
+    const leaf = path.at(-1);
+    // Classify off the declaration, never off what the member holds: a
+    // `stringArray` slot holds an array node, and an optional sub-schema nobody
+    // has written yet holds nothing.
+    const declared = getConfigurationSchemaDefinition(node)?.[leaf];
+    if (isConfigurationSchemaType(declared)) {
+        // eslint-disable-next-line no-restricted-syntax -- this is setConf
+        node.setSubschema(leaf, value);
+    }
+    else {
+        // eslint-disable-next-line no-restricted-syntax -- this is setConf
+        node.setSlot(leaf, value);
+    }
+}
+// A sub-schema of independent settings, whose members a bag names one by one.
+// A channel — a sub-schema with a shorthand — takes one written value, so a
+// bag replaces it whole: `{ field }` after `{ field, domain }` is a facet with
+// no domain, and a merge would leave the old domain standing.
+function namespaceMetadata(member) {
+    const meta = isStateTreeNode(member)
+        ? getConfigurationSchemaMetadata(getType(member))
+        : undefined;
+    return meta?.options.shorthand === undefined ? meta : undefined;
+}
+function writeConfMember(conf, key, value) {
+    const member = conf[key];
+    const namespace = isPlainObject(value) ? namespaceMetadata(member) : undefined;
+    if (namespace) {
+        for (const [k, v] of Object.entries(preProcessSnapshotWith(namespace, value))) {
+            writeConfMember(member, k, v);
+        }
+    }
+    else {
+        writeConfPath(conf, [key], value);
+    }
+}
+/**
+ * #api core/configuration
+ * Write a settings bag — a session spec's track entry, a share link, an agent
+ * call — onto a config. Each key names a member: a slot or a channel is written
+ * whole, as `setConf` writes it, so `null` resets it (ADR-146); a namespace's
+ * object names members inside it, at any depth, and the ones it leaves out
+ * keep their values. The config's own lift and checks run over the bag first,
+ * and each namespace's over its part, so a shorthand or a legacy key reads the
+ * same here as in `config.json`. A key the config does not declare is reported
+ * for the caller to route or refuse, and a declared key whose write throws
+ * costs that key alone.
+ */
+export function applyConfSettings(target, settings) {
+    const conf = isConfigurationModel(target) ? target : target.configuration;
+    const meta = getConfigurationSchemaMetadata(conf);
+    const values = meta ? preProcessSnapshotWith(meta, settings) : settings;
+    const report = { applied: [], undeclared: {}, failed: [] };
+    for (const [key, value] of Object.entries(values)) {
+        const declared = Object.hasOwn(meta?.definition ?? {}, key)
+            ? meta.definition[key]
+            : undefined;
+        if (declared === undefined || isConstantEntry(declared)) {
+            report.undeclared[key] = value;
+            continue;
+        }
+        try {
+            writeConfMember(conf, key, value);
+            report.applied.push(key);
+        }
+        catch (e) {
+            report.failed.push({ key, error: `${e}` });
+        }
+    }
+    return report;
+}

package/esm/configuration/index.d.ts

@@ -1,3 +1,32 @@
-export { ConfigurationReference, ConfigurationSchema, } from './configurationSchema.ts';
-export type { AnyConfiguration, AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSlot, AnyConfigurationSlotType, } from './types.ts';
-export * from './util.ts';
+export { ConfigurationReference, ConfigurationSchema, hydrateTrackConfig, } from './configurationSchema.ts';
+export type { ConfigurationSchemaDefinition, RetiredSpelling, } from './configurationSchema.ts';
+export { ConfigurationSchemaUnion, arraySlotUnion, } from './configurationSchemaUnion.ts';
+export type { ConfigurationSchemaUnionType } from './configurationSchemaUnion.ts';
+export type { ConfigSlotDefinition } from './configurationSlot.ts';
+export type { AnyConfiguration, AnyConfigurationModel, AnyConfigurationSchemaType, AnyConfigurationSnapshot, ConfigModelForFields, ConfigNodeActions, ConfigNodeBrand, ConfigNodeProps, ConfigurationSchemaForModel, ConfigurationSlotName, ConfigurationSlotPath, ConfigurationSlotPathValue, ConfigurationSlotValue, ConfigurationSnapshot, HostChecksSlotNames, IdentifierSlotDef, PluggableConfigNode, TypeSlotDef, } from './types.ts';
+export { getConfigurationSchemaDefinition, getConfigurationSchemaMetadata, getConfigurationSchemaUnion, } from './schemaRegistry.ts';
+export type { ConfigurationSchemaUnionMetadata } from './schemaRegistry.ts';
+export { getTypeNamesFromExplicitlyTypedUnion, isBareConfigurationSchemaType, isConfigurationModel, isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.ts';
+export { FormatAboutConfigSchemaFactory } from './formatAboutConfigSchema.ts';
+export { DEFAULT_FORMAT_DETAILS_DEPTH, FormatDetailsConfigSchemaFactory, } from './formatDetailsConfigSchema.ts';
+export { mergeFormatCallbacks } from './mergeFormatCallbacks.ts';
+export { readConfObject, readConfigValue } from './readConfObject.ts';
+export { applyConfSettings, getConf, setConf } from './getConf.ts';
+export type { ConfSettingsReport } from './getConf.ts';
+export { fillLocations } from './fillLocations.ts';
+export { applyRetiredSpellings, liftRetiredSpellings, preProcessConfigSnapshot, preProcessSnapshotWith, } from './snapshotPreprocess.ts';
+export { shorthandTargets, shorthandTargetsOf } from './schemaTypes.ts';
+export type { ShorthandForm } from './schemaTypes.ts';
+export { requirementProblems } from './requirements.ts';
+export type { ConfigurationSchemaRequirement, RequirementProblem, } from './requirements.ts';
+export { expandTabixShorthand, indexSnapshot, requestedIndexType, tabixIndexSnapshot, } from './tabixShorthand.ts';
+export { expandUriShorthand } from './uriShorthand.ts';
+export { bamIndexFields, bamIndexSchema } from './bamIndexFields.ts';
+export { tabixIndexFields, tabixIndexSchema } from './tabixIndexFields.ts';
+export { fillIndexType, indexSuffix, isCsiLocation } from './indexType.ts';
+export type { IndexType, SiblingIndexType } from './indexType.ts';
+export { evaluateJexl, isCallbackValue } from './slotValueUtils.ts';
+export { toCallbackValue, toFixedValue } from './configurationSlot.ts';
+export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, slotChoices, slotValueRefusal, } from './slotFacade.ts';
+export type { SlotFacade } from './slotFacade.ts';
+export { fullConfSnapshot } from './fullConfSnapshot.ts';

package/esm/configuration/index.js

@@ -1,2 +1,27 @@
-export { ConfigurationReference, ConfigurationSchema, } from "./configurationSchema.js";
-export * from "./util.js";
+export { ConfigurationReference, ConfigurationSchema, hydrateTrackConfig, } from './configurationSchema.js';
+export { ConfigurationSchemaUnion, arraySlotUnion, } from './configurationSchemaUnion.js';
+export { getConfigurationSchemaDefinition, 
+// exported for scripts/generateConfigManifest.ts, which needs the
+// preProcessSnapshot off a schema whose pluggable type does not expose one —
+// TextSearchAdapterType, where the shorthand is nonetheless the documented
+// way to write the config
+getConfigurationSchemaMetadata, getConfigurationSchemaUnion, } from './schemaRegistry.js';
+export { getTypeNamesFromExplicitlyTypedUnion, isBareConfigurationSchemaType, isConfigurationModel, isConfigurationSchemaType, isConstantEntry, isSlotDefinitionEntry, } from './schemaTypes.js';
+export { FormatAboutConfigSchemaFactory } from './formatAboutConfigSchema.js';
+export { DEFAULT_FORMAT_DETAILS_DEPTH, FormatDetailsConfigSchemaFactory, } from './formatDetailsConfigSchema.js';
+export { mergeFormatCallbacks } from './mergeFormatCallbacks.js';
+export { readConfObject, readConfigValue } from './readConfObject.js';
+export { applyConfSettings, getConf, setConf } from './getConf.js';
+export { fillLocations } from './fillLocations.js';
+export { applyRetiredSpellings, liftRetiredSpellings, preProcessConfigSnapshot, preProcessSnapshotWith, } from './snapshotPreprocess.js';
+export { shorthandTargets, shorthandTargetsOf } from './schemaTypes.js';
+export { requirementProblems } from './requirements.js';
+export { expandTabixShorthand, indexSnapshot, requestedIndexType, tabixIndexSnapshot, } from './tabixShorthand.js';
+export { expandUriShorthand } from './uriShorthand.js';
+export { bamIndexFields, bamIndexSchema } from './bamIndexFields.js';
+export { tabixIndexFields, tabixIndexSchema } from './tabixIndexFields.js';
+export { fillIndexType, indexSuffix, isCsiLocation } from './indexType.js';
+export { evaluateJexl, isCallbackValue } from './slotValueUtils.js';
+export { toCallbackValue, toFixedValue } from './configurationSlot.js';
+export { getSlotDefinition, isConfigurationSlot, makeSlotFacade, slotChoices, slotValueRefusal, } from './slotFacade.js';
+export { fullConfSnapshot } from './fullConfSnapshot.js';

package/esm/configuration/indexType.d.ts

@@ -0,0 +1,26 @@
+/** The sibling index format of a family: TBI for tabix, BAI for BAM. */
+export type SiblingIndexType = 'TBI' | 'BAI';
+export type IndexType = SiblingIndexType | 'CSI';
+/** The extension an index of this type carries: `CSI` → `.csi`, `TBI` → `.tbi`. */
+export declare function indexSuffix(indexType: IndexType): string;
+/**
+ * Whether a file location names a CSI. htslib writes `.csi` in place of a `.bai`
+ * or a `.tbi` for a reference over 512 Mb and on request at any size, so the
+ * extension is the only thing distinguishing the two parsers.
+ *
+ * `makeIndexType` in `util/tracks.ts` asks this of a bare filename, for the
+ * guessers and add-track forms that WRITE an `indexType` beside the location.
+ * Those stay: a config the CLI or jbrowse-img writes is read by older JBrowse
+ * versions, which have no inference to fall back on.
+ */
+export declare function isCsiLocation(location: unknown): boolean;
+/**
+ * An index sub-schema's snapshot with `indexType` filled in from the location it
+ * names, where it states none. Only CSI is ever filled in — the sibling format
+ * is the slot's own default.
+ *
+ * Belongs to the sub-schema rather than to the `uri` shorthand because it has to
+ * cover the paths no shorthand runs on: a long-form config, and an add-track
+ * form that writes a location and nothing else.
+ */
+export declare function fillIndexType(snap: Record<string, unknown>): Record<string, unknown>;

package/esm/configuration/indexType.js

@@ -0,0 +1,38 @@
+import { isPlainObject } from '../util/objectUtils.js';
+/** The extension an index of this type carries: `CSI` → `.csi`, `TBI` → `.tbi`. */
+export function indexSuffix(indexType) {
+    return `.${indexType.toLowerCase()}`;
+}
+/**
+ * Whether a file location names a CSI. htslib writes `.csi` in place of a `.bai`
+ * or a `.tbi` for a reference over 512 Mb and on request at any size, so the
+ * extension is the only thing distinguishing the two parsers.
+ *
+ * `makeIndexType` in `util/tracks.ts` asks this of a bare filename, for the
+ * guessers and add-track forms that WRITE an `indexType` beside the location.
+ * Those stay: a config the CLI or jbrowse-img writes is read by older JBrowse
+ * versions, which have no inference to fall back on.
+ */
+export function isCsiLocation(location) {
+    if (!isPlainObject(location)) {
+        return false;
+    }
+    const { uri, localPath } = location;
+    const name = typeof uri === 'string' ? uri : localPath;
+    // a presigned url carries its query string after the name
+    return typeof name === 'string' && /\.csi$/i.test(name.split(/[?#]/)[0]);
+}
+/**
+ * An index sub-schema's snapshot with `indexType` filled in from the location it
+ * names, where it states none. Only CSI is ever filled in — the sibling format
+ * is the slot's own default.
+ *
+ * Belongs to the sub-schema rather than to the `uri` shorthand because it has to
+ * cover the paths no shorthand runs on: a long-form config, and an add-track
+ * form that writes a location and nothing else.
+ */
+export function fillIndexType(snap) {
+    return snap.indexType === undefined && isCsiLocation(snap.location)
+        ? { ...snap, indexType: 'CSI' }
+        : snap;
+}

package/esm/configuration/mergeFormatCallbacks.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Combine the tiers of an object-returning format callback (`formatDetails` on
+ * the feature-details panel, `formatAbout` on the About dialog), earliest
+ * first, so a track's object is spread over the session-wide one and can
+ * override individual keys the global callback added.
+ *
+ * A tier that returns something other than an object is an authoring mistake,
+ * `"jexl:feature.name"` where `"jexl:{name:feature.name}"` was meant, and it
+ * throws rather than vanishing: spread, the string became rows keyed 0, 1, 2,
+ * and dropped, the author's callback silently did nothing. A tier returning
+ * null or undefined has nothing to add. `null` and `undefined` *values* survive:
+ * they are how a callback hides a field, and the panels filter them downstream.
+ */
+export declare function mergeFormatCallbacks(...tiers: unknown[]): Record<string, unknown>;

package/esm/configuration/mergeFormatCallbacks.js

@@ -0,0 +1,27 @@
+import { isPlainObject } from '../util/objectUtils.js';
+/**
+ * Combine the tiers of an object-returning format callback (`formatDetails` on
+ * the feature-details panel, `formatAbout` on the About dialog), earliest
+ * first, so a track's object is spread over the session-wide one and can
+ * override individual keys the global callback added.
+ *
+ * A tier that returns something other than an object is an authoring mistake,
+ * `"jexl:feature.name"` where `"jexl:{name:feature.name}"` was meant, and it
+ * throws rather than vanishing: spread, the string became rows keyed 0, 1, 2,
+ * and dropped, the author's callback silently did nothing. A tier returning
+ * null or undefined has nothing to add. `null` and `undefined` *values* survive:
+ * they are how a callback hides a field, and the panels filter them downstream.
+ */
+export function mergeFormatCallbacks(...tiers) {
+    const out = {};
+    for (const tier of tiers) {
+        if (tier == null) {
+            continue;
+        }
+        if (!isPlainObject(tier)) {
+            throw new Error(`a format callback returned ${Array.isArray(tier) ? 'an array' : `a ${typeof tier}`} where an object of fields was expected, e.g. "jexl:{name:feature.name}" rather than "jexl:feature.name"`);
+        }
+        Object.assign(out, tier);
+    }
+    return out;
+}

package/esm/configuration/readConfObject.d.ts

@@ -0,0 +1,34 @@
+import type { Feature } from '../util/index.ts';
+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`.
+ *
+ * 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.
+ *
+ * @param model - instance of ConfigurationSchema
+ * @param slotPaths - array of paths to read
+ * @param args - extra arguments e.g. for a feature callback,
+ *  will be sent to each of the slotNames
+ */
+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.
+ */
+export declare function readConfigValue<T>(config: Record<string, unknown>, key: string | string[], feature: Feature, jexl: JexlInstance): T;