@platforma-open/milaboratories.vj-usage.model 2.1.5 → 2.1.6

package/dist/bundle.js

@@ -4,6 +4,113 @@
     (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global["block-model"] = {}));
 })(this, (function (exports) { 'use strict';
 
+    /**
+     * BlockStorage - Typed storage abstraction for block persistent data.
+     *
+     * This module provides:
+     * - A typed structure for block storage with versioning and plugin support
+     * - Utility functions for manipulating storage
+     * - Handler interfaces for model-level customization
+     *
+     * @module block_storage
+     */
+    // =============================================================================
+    // Core Types
+    // =============================================================================
+    /**
+     * Discriminator key for BlockStorage format detection.
+     * This unique hash-based key identifies data as BlockStorage vs legacy formats.
+     */
+    const BLOCK_STORAGE_KEY = '__pl_a7f3e2b9__';
+    /**
+     * Current BlockStorage schema version.
+     * Increment this when the storage structure itself changes (not block state migrations).
+     */
+    const BLOCK_STORAGE_SCHEMA_VERSION = 'v1';
+    /**
+     * Default data version for new blocks without migrations.
+     * Unique identifier ensures blocks are created via DataModel API.
+     */
+    const DATA_MODEL_DEFAULT_VERSION = '__pl_v1_d4e8f2a1__';
+    /**
+     * Type guard to check if a value is a valid BlockStorage object.
+     * Checks for the discriminator key and valid schema version.
+     */
+    function isBlockStorage(value) {
+        if (value === null || typeof value !== 'object')
+            return false;
+        const obj = value;
+        const schemaVersion = obj[BLOCK_STORAGE_KEY];
+        // Currently only 'v1' is valid, but this allows future versions
+        return schemaVersion === 'v1'; // Add more versions as schema evolves
+    }
+    // =============================================================================
+    // Factory Functions
+    // =============================================================================
+    /**
+     * Creates a BlockStorage with the given initial data
+     *
+     * @param initialData - The initial data value (defaults to empty object)
+     * @param version - The initial data version key (defaults to DATA_MODEL_DEFAULT_VERSION)
+     * @returns A new BlockStorage instance with discriminator key
+     */
+    function createBlockStorage(initialData = {}, version = DATA_MODEL_DEFAULT_VERSION) {
+        return {
+            [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
+            __dataVersion: version,
+            __data: initialData,
+        };
+    }
+    /**
+     * Normalizes raw storage data to BlockStorage format.
+     * If the input is already a BlockStorage, returns it as-is.
+     * If the input is legacy format (raw state), wraps it in BlockStorage structure.
+     *
+     * @param raw - Raw storage data (may be legacy format or BlockStorage)
+     * @returns Normalized BlockStorage
+     */
+    function normalizeBlockStorage(raw) {
+        if (isBlockStorage(raw)) {
+            const storage = raw;
+            return {
+                ...storage,
+                // Fix for early released version where __dataVersion was a number
+                __dataVersion: typeof storage.__dataVersion === 'number'
+                    ? DATA_MODEL_DEFAULT_VERSION
+                    : storage.__dataVersion,
+            };
+        }
+        // Legacy format: raw is the state directly
+        return createBlockStorage(raw);
+    }
+    // =============================================================================
+    // Data Access & Update Functions
+    // =============================================================================
+    /**
+     * Gets the data from BlockStorage
+     *
+     * @param storage - The BlockStorage instance
+     * @returns The data value
+     */
+    function getStorageData(storage) {
+        return storage.__data;
+    }
+    /**
+     * Updates the data in BlockStorage (immutable)
+     *
+     * @param storage - The current BlockStorage
+     * @param payload - The update payload with operation and value
+     * @returns A new BlockStorage with updated data
+     */
+    function updateStorageData(storage, payload) {
+        switch (payload.operation) {
+            case 'update-data':
+                return { ...storage, __data: payload.value };
+            default:
+                throw new Error(`Unknown storage operation: ${payload.operation}`);
+        }
+    }
+
     //
     // Helpers
     //
@@ -4690,6 +4797,9 @@
         Table: {
             OrderPriority: 'pl7.app/table/orderPriority'},
         Trace: 'pl7.app/trace',
+        VDJ: {
+            IsAssemblingFeature: 'pl7.app/vdj/isAssemblingFeature',
+        },
     };
     const ValueTypeSchema = z.enum(['Int', 'Long', 'Float', 'Double', 'String']);
     const AnnotationJson = {
@@ -4719,6 +4829,7 @@
         [Annotation.Sequence.IsAnnotation]: z.boolean(),
         [Annotation.Table.OrderPriority]: z.number(),
         [Annotation.Trace]: z.record(z.string(), z.unknown()),
+        [Annotation.VDJ.IsAssemblingFeature]: z.boolean(),
     };
     /// Helper function for reading plain annotation values
     function readAnnotation(spec, key) {
@@ -6094,6 +6205,30 @@
             }
             return result;
         };
+        const countUniqueLabels = (result) => result === undefined ? 0 : new Set(result.map((c) => c.label)).size;
+        // Post-processing: try removing types one by one (lowest importance first) to minimize the label set
+        // Accepts removal if it doesn't decrease the number of unique labels (cardinality)
+        const minimizeTypeSet = (typeSet) => {
+            const initialResult = calculate(typeSet);
+            if (initialResult === undefined) {
+                return typeSet;
+            }
+            const currentCardinality = countUniqueLabels(initialResult);
+            // Get types sorted by importance ascending (lowest first), excluding forced elements
+            const removableSorted = [...typeSet]
+                .filter((t) => !forceTraceElements?.has(t.split('@')[0])
+                && !(ops.includeNativeLabel && t === LabelTypeFull))
+                .sort((a, b) => (importances.get(a) ?? 0) - (importances.get(b) ?? 0));
+            for (const typeToRemove of removableSorted) {
+                const reducedSet = new Set(typeSet);
+                reducedSet.delete(typeToRemove);
+                const candidateResult = calculate(reducedSet);
+                if (candidateResult !== undefined && countUniqueLabels(candidateResult) >= currentCardinality) {
+                    typeSet.delete(typeToRemove);
+                }
+            }
+            return typeSet;
+        };
         if (mainTypes.length === 0) {
             if (secondaryTypes.length !== 0)
                 throw new Error('Non-empty secondary types list while main types list is empty.');
@@ -6119,16 +6254,20 @@
             if (additionalType >= 0)
                 currentSet.add(mainTypes[additionalType]);
             const candidateResult = calculate(currentSet);
-            // checking if labels uniquely separate our records
-            if (candidateResult !== undefined && new Set(candidateResult.map((c) => c.label)).size === values.length)
-                return candidateResult;
+            if (candidateResult !== undefined && countUniqueLabels(candidateResult) === values.length) {
+                minimizeTypeSet(currentSet);
+                return calculate(currentSet);
+            }
             additionalType++;
             if (additionalType >= mainTypes.length) {
                 includedTypes++;
                 additionalType = includedTypes;
             }
         }
-        return calculate(new Set([...mainTypes, ...secondaryTypes]), true);
+        // Fallback: include all types, then try to minimize
+        const fallbackSet = new Set([...mainTypes, ...secondaryTypes]);
+        minimizeTypeSet(fallbackSet);
+        return calculate(fallbackSet, true);
     }
 
     const PCD_PREFIX = 'PColumnData/';
@@ -7231,28 +7370,19 @@
         }
     }
     /** Main entry point to the API available within model lambdas (like outputs, sections, etc..) */
-    class RenderCtx {
+    class RenderCtxBase {
         ctx;
         constructor() {
             this.ctx = getCfgRenderCtx();
         }
-        _argsCache;
-        get args() {
-            if (this._argsCache === undefined) {
-                const raw = this.ctx.args;
+        _dataCache;
+        get data() {
+            if (this._dataCache === undefined) {
+                const raw = this.ctx.data;
                 const value = typeof raw === 'function' ? raw() : raw;
-                this._argsCache = { v: JSON.parse(value) };
+                this._dataCache = { v: value ? JSON.parse(value) : {} };
             }
-            return this._argsCache.v;
-        }
-        _uiStateCache;
-        get uiState() {
-            if (this._uiStateCache === undefined) {
-                const raw = this.ctx.uiState;
-                const value = typeof raw === 'function' ? raw() : raw;
-                this._uiStateCache = { v: value ? JSON.parse(value) : {} };
-            }
-            return this._uiStateCache.v;
+            return this._dataCache.v;
         }
         // lazy rendering because this feature is rarely used
         _activeArgsCache;
@@ -7363,8 +7493,29 @@
             this.ctx.logError(msg);
         }
     }
+    /** Render context for legacy v1/v2 blocks - provides backward compatibility */
+    class RenderCtxLegacy extends RenderCtxBase {
+        _argsCache;
+        get args() {
+            if (this._argsCache === undefined) {
+                const raw = this.ctx.args;
+                const value = typeof raw === 'function' ? raw() : raw;
+                this._argsCache = { v: JSON.parse(value) };
+            }
+            return this._argsCache.v;
+        }
+        _uiStateCache;
+        get uiState() {
+            if (this._uiStateCache === undefined) {
+                const raw = this.ctx.uiState;
+                const value = typeof raw === 'function' ? raw() : raw;
+                this._uiStateCache = { v: value ? JSON.parse(value) : {} };
+            }
+            return this._uiStateCache.v;
+        }
+    }
 
-    var version = "1.51.2";
+    var version = "1.53.3";
 
     const PlatformaSDKVersion = version;
 
@@ -7408,7 +7559,7 @@
         output(key, cfgOrRf, flags = {}) {
             if (typeof cfgOrRf === 'function') {
                 const handle = `output#${key}`;
-                tryRegisterCallback(handle, () => cfgOrRf(new RenderCtx()));
+                tryRegisterCallback(handle, () => cfgOrRf(new RenderCtxLegacy()));
                 return new BlockModel({
                     ...this.config,
                     outputs: {
@@ -7445,7 +7596,7 @@
         }
         argsValid(cfgOrRf) {
             if (typeof cfgOrRf === 'function') {
-                tryRegisterCallback('inputsValid', () => cfgOrRf(new RenderCtx()));
+                tryRegisterCallback('inputsValid', () => cfgOrRf(new RenderCtxLegacy()));
                 return new BlockModel({
                     ...this.config,
                     inputsValid: {
@@ -7466,7 +7617,7 @@
                 return this.sections(getImmediate(arrOrCfgOrRf));
             }
             else if (typeof arrOrCfgOrRf === 'function') {
-                tryRegisterCallback('sections', () => arrOrCfgOrRf(new RenderCtx()));
+                tryRegisterCallback('sections', () => arrOrCfgOrRf(new RenderCtxLegacy()));
                 return new BlockModel({
                     ...this.config,
                     sections: {
@@ -7484,7 +7635,7 @@
         }
         /** Sets a rendering function to derive block title, shown for the block in the left blocks-overview panel. */
         title(rf) {
-            tryRegisterCallback('title', () => rf(new RenderCtx()));
+            tryRegisterCallback('title', () => rf(new RenderCtxLegacy()));
             return new BlockModel({
                 ...this.config,
                 title: {
@@ -7494,7 +7645,7 @@
             });
         }
         subtitle(rf) {
-            tryRegisterCallback('subtitle', () => rf(new RenderCtx()));
+            tryRegisterCallback('subtitle', () => rf(new RenderCtxLegacy()));
             return new BlockModel({
                 ...this.config,
                 subtitle: {
@@ -7504,7 +7655,7 @@
             });
         }
         tags(rf) {
-            tryRegisterCallback('tags', () => rf(new RenderCtx()));
+            tryRegisterCallback('tags', () => rf(new RenderCtxLegacy()));
             return new BlockModel({
                 ...this.config,
                 tags: {
@@ -7571,7 +7722,10 @@
             if (this.config.initialArgs === undefined)
                 throw new Error('Initial arguments not set.');
             const config = {
+                v4: undefined,
                 v3: {
+                    configVersion: 3,
+                    modelAPIVersion: 1,
                     sdkVersion: PlatformaSDKVersion,
                     renderingMode: this.config.renderingMode,
                     initialArgs: this.config.initialArgs,
@@ -7611,6 +7765,259 @@
         }
     }
 
+    /**
+     * BlockStorage VM Integration - Internal module for VM-based storage operations.
+     *
+     * This module auto-registers internal callbacks that the middle layer can invoke
+     * to perform storage transformations. Block developers never interact with these
+     * directly - they only see `state`.
+     *
+     * Registered callbacks (all prefixed with `__pl_` for internal SDK use):
+     * - `__pl_storage_applyUpdate`: (currentStorageJson, payload) => updatedStorageJson
+     * - `__pl_storage_debugView`: (rawStorage) => JSON string with storage debug view
+     * - `__pl_storage_migrate`: (currentStorageJson) => MigrationResult
+     * - `__pl_args_derive`: (storageJson) => ArgsDeriveResult
+     * - `__pl_prerunArgs_derive`: (storageJson) => ArgsDeriveResult
+     *
+     * Callbacks registered by DataModel.registerCallbacks():
+     * - `__pl_data_initial`: () => initial data
+     * - `__pl_data_upgrade`: (versioned) => DataMigrationResult
+     * - `__pl_storage_initial`: () => initial BlockStorage as JSON string
+     *
+     * @module block_storage_vm
+     * @internal
+     */
+    /**
+     * Normalizes raw storage data and extracts state.
+     * Handles all formats:
+     * - New BlockStorage format (has discriminator)
+     * - Legacy V1/V2 format ({ args, uiState })
+     * - Raw V3 state (any other format)
+     *
+     * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)
+     * @returns Object with normalized storage and extracted state
+     */
+    function normalizeStorage(rawStorage) {
+        // Handle undefined/null
+        if (rawStorage === undefined || rawStorage === null) {
+            const storage = createBlockStorage({});
+            return { storage, data: {} };
+        }
+        // Parse JSON string if needed
+        let parsed = rawStorage;
+        if (typeof rawStorage === 'string') {
+            try {
+                parsed = JSON.parse(rawStorage);
+            }
+            catch {
+                // If parsing fails, treat string as the data
+                const storage = createBlockStorage(rawStorage);
+                return { storage, data: rawStorage };
+            }
+        }
+        // Check for BlockStorage format (has discriminator)
+        if (isBlockStorage(parsed)) {
+            const storage = normalizeBlockStorage(parsed);
+            return { storage, data: getStorageData(storage) };
+        }
+        // Check for legacy V1/V2 format: { args, uiState }
+        if (isLegacyModelV1ApiFormat(parsed)) {
+            // For legacy format, the whole object IS the data
+            const storage = createBlockStorage(parsed);
+            return { storage, data: parsed };
+        }
+        // Raw V3 data - wrap it
+        const storage = createBlockStorage(parsed);
+        return { storage, data: parsed };
+    }
+    /**
+     * Applies a state update to existing storage.
+     * Used when setData is called from the frontend.
+     *
+     * @param currentStorageJson - Current storage as JSON string (must be defined)
+     * @param newData - New data from application
+     * @returns Updated storage as JSON string
+     */
+    function applyStorageUpdate(currentStorageJson, payload) {
+        const { storage: currentStorage } = normalizeStorage(currentStorageJson);
+        // Update data while preserving other storage fields (version, plugins)
+        const updatedStorage = updateStorageData(currentStorage, payload);
+        return JSON.stringify(updatedStorage);
+    }
+    /**
+     * Checks if data is in legacy Model API v1 format.
+     * Legacy format has { args, uiState? } at top level without the BlockStorage discriminator.
+     */
+    function isLegacyModelV1ApiFormat(data) {
+        if (data === null || typeof data !== 'object')
+            return false;
+        if (isBlockStorage(data))
+            return false;
+        const obj = data;
+        return 'args' in obj;
+    }
+    // =============================================================================
+    // Auto-register internal callbacks when module is loaded in VM
+    // =============================================================================
+    // Register apply update callback (requires existing storage)
+    tryRegisterCallback('__pl_storage_applyUpdate', (currentStorageJson, payload) => {
+        return applyStorageUpdate(currentStorageJson, payload);
+    });
+    /**
+     * Gets storage debug view from raw storage data.
+     * Returns structured debug info about the storage state.
+     *
+     * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)
+     * @returns JSON string with storage debug view
+     */
+    function getStorageDebugView(rawStorage) {
+        const { storage } = normalizeStorage(rawStorage);
+        const debugView = {
+            dataVersion: storage.__dataVersion,
+            data: storage.__data,
+        };
+        return stringifyJson(debugView);
+    }
+    // Register debug view callback
+    tryRegisterCallback('__pl_storage_debugView', (rawStorage) => {
+        return getStorageDebugView(rawStorage);
+    });
+    /**
+     * Runs storage migration using the DataModel's migrate callback.
+     * This is the main entry point for the middle layer to trigger migrations.
+     *
+     * Uses the '__pl_data_upgrade' callback registered by DataModel.registerCallbacks() which:
+     * - Handles all migration logic internally
+     * - Returns { version, data, warning? } - warning present if reset to initial data
+     *
+     * @param currentStorageJson - Current storage as JSON string (or undefined)
+     * @returns MigrationResult
+     */
+    function migrateStorage(currentStorageJson) {
+        // Get the callback registry context
+        const ctx = tryGetCfgRenderCtx();
+        if (ctx === undefined) {
+            return { error: 'Not in config rendering context' };
+        }
+        // Normalize storage to get current data and version
+        const { storage: currentStorage, data: currentData } = normalizeStorage(currentStorageJson);
+        const currentVersion = currentStorage.__dataVersion;
+        // Helper to create storage with given data and version
+        const createStorageJson = (data, version) => {
+            return JSON.stringify({
+                ...currentStorage,
+                __dataVersion: version,
+                __data: data,
+            });
+        };
+        // Get the migrate callback (registered by DataModel.registerCallbacks())
+        const migrateCallback = ctx.callbackRegistry['__pl_data_upgrade'];
+        if (typeof migrateCallback !== 'function') {
+            return { error: '__pl_data_upgrade callback not found (DataModel not registered)' };
+        }
+        // Call the migrator's migrate function
+        let result;
+        try {
+            result = migrateCallback({ version: currentVersion, data: currentData });
+        }
+        catch (e) {
+            const errorMsg = e instanceof Error ? e.message : String(e);
+            return { error: `migrate() threw: ${errorMsg}` };
+        }
+        // Build info message
+        const info = result.version === currentVersion
+            ? `No migration needed (${currentVersion})`
+            : result.warning
+                ? `Reset to initial data (${result.version})`
+                : `Migrated ${currentVersion}→${result.version}`;
+        return {
+            newStorageJson: createStorageJson(result.data, result.version),
+            info,
+            warn: result.warning,
+        };
+    }
+    // Register migrate callback
+    tryRegisterCallback('__pl_storage_migrate', (currentStorageJson) => {
+        return migrateStorage(currentStorageJson);
+    });
+    /**
+     * Derives args from storage using the registered 'args' callback.
+     * This extracts data from storage and passes it to the block's args() function.
+     *
+     * @param storageJson - Storage as JSON string
+     * @returns ArgsDeriveResult with derived args or error
+     */
+    function deriveArgsFromStorage(storageJson) {
+        const ctx = tryGetCfgRenderCtx();
+        if (ctx === undefined) {
+            return { error: 'Not in config rendering context' };
+        }
+        // Extract data from storage
+        const { data } = normalizeStorage(storageJson);
+        // Get the args callback (registered by BlockModelV3.args())
+        const argsCallback = ctx.callbackRegistry['args'];
+        if (typeof argsCallback !== 'function') {
+            return { error: 'args callback not found' };
+        }
+        // Call the args callback with extracted data
+        try {
+            const result = argsCallback(data);
+            return { value: result };
+        }
+        catch (e) {
+            const errorMsg = e instanceof Error ? e.message : String(e);
+            return { error: `args() threw: ${errorMsg}` };
+        }
+    }
+    // Register args derivation callback
+    tryRegisterCallback('__pl_args_derive', (storageJson) => {
+        return deriveArgsFromStorage(storageJson);
+    });
+    /**
+     * Derives prerunArgs from storage using the registered 'prerunArgs' callback.
+     * Falls back to 'args' callback if 'prerunArgs' is not defined.
+     *
+     * @param storageJson - Storage as JSON string
+     * @returns ArgsDeriveResult with derived prerunArgs or error
+     */
+    function derivePrerunArgsFromStorage(storageJson) {
+        const ctx = tryGetCfgRenderCtx();
+        if (ctx === undefined) {
+            return { error: 'Not in config rendering context' };
+        }
+        // Extract data from storage
+        const { data } = normalizeStorage(storageJson);
+        // Try prerunArgs callback first
+        const prerunArgsCallback = ctx.callbackRegistry['prerunArgs'];
+        if (typeof prerunArgsCallback === 'function') {
+            try {
+                const result = prerunArgsCallback(data);
+                return { value: result };
+            }
+            catch (e) {
+                const errorMsg = e instanceof Error ? e.message : String(e);
+                return { error: `prerunArgs() threw: ${errorMsg}` };
+            }
+        }
+        // Fall back to args callback
+        const argsCallback = ctx.callbackRegistry['args'];
+        if (typeof argsCallback !== 'function') {
+            return { error: 'args callback not found (fallback from missing prerunArgs)' };
+        }
+        try {
+            const result = argsCallback(data);
+            return { value: result };
+        }
+        catch (e) {
+            const errorMsg = e instanceof Error ? e.message : String(e);
+            return { error: `args() threw (fallback): ${errorMsg}` };
+        }
+    }
+    // Register prerunArgs derivation callback
+    tryRegisterCallback('__pl_prerunArgs_derive', (storageJson) => {
+        return derivePrerunArgsFromStorage(storageJson);
+    });
+
     function getAllRelatedColumns(ctx, predicate) {
         // if current block doesn't produce own columns then use all columns from result pool
         const columns = new PColumnCollection();
@@ -7901,13 +8308,32 @@
         errors: z.lazy(() => ErrorShape.array()).optional(),
     });
 
+    function getDefaultBlockLabel(data) {
+        const parts = [];
+        // Add dataset name
+        if (data.datasetLabel) {
+            parts.push(data.datasetLabel);
+        }
+        // Add allele/gene
+        parts.push(data.allele ? 'Allele' : 'Gene');
+        // Add chain info for single-cell datasets
+        if (data.isSingleCell && data.chainLabel) {
+            parts.push(data.chainLabel);
+        }
+        return parts.join(' - ');
+    }
+
     const model = BlockModel.create()
         .withArgs({
+        defaultBlockLabel: getDefaultBlockLabel({
+            allele: false,
+            isSingleCell: false,
+        }),
+        customBlockLabel: '',
         scChain: 'A',
         allele: false,
     })
         .withUiState({
-        blockTitle: 'V/J Usage',
         weightedFlag: true,
         vUsagePlotState: {
             title: 'V Usage',
@@ -7920,7 +8346,7 @@
             },
         },
         jUsagePlotState: {
-            title: 'V Usage',
+            title: 'J Usage',
             template: 'heatmapClustered',
             currentTab: null,
             layersSettings: {
@@ -7971,7 +8397,8 @@
         return createPFrameForGraphs(ctx, pCols);
     })
         .output('isRunning', (ctx) => ctx.outputs?.getIsReadyOrError() === false)
-        .title((ctx) => ctx.uiState?.blockTitle ?? 'V/J Usage')
+        .title(() => 'V/J Usage')
+        .subtitle((ctx) => ctx.args.customBlockLabel || ctx.args.defaultBlockLabel)
         .sections((_) => [
         { type: 'link', href: '/', label: 'V Gene Usage' },
         { type: 'link', href: '/jUsage', label: 'J Gene Usage' },
@@ -7979,6 +8406,7 @@
     ])
         .done(2);
 
+    exports.getDefaultBlockLabel = getDefaultBlockLabel;
     exports.model = model;
 
 }));