@milaboratories/milaboratories.ui-examples.model 1.3.22 → 1.4.1

package/.turbo/turbo-build.log

@@ -1,16 +1,16 @@
  WARN  Issue while reading "/home/runner/_work/platforma/platforma/.npmrc". Failed to replace env in config: ${NPMJS_TOKEN}
 
-> @milaboratories/milaboratories.ui-examples.model@1.3.22 build /home/runner/_work/platforma/platforma/etc/blocks/ui-examples/model
+> @milaboratories/milaboratories.ui-examples.model@1.4.1 build /home/runner/_work/platforma/platforma/etc/blocks/ui-examples/model
 > ts-builder build --target block-model && block-tools build-model
 
 Building block-model project...
 ↳ rollup -c /configs/rollup.block-model.config.js
 
 ./src/index.ts → dist, dist...
-created dist, dist in 3.2s
+created dist, dist in 4.3s
 
 ./src/index.ts → dist...
 (!) Circular dependency
 ../../../../sdk/model/dist/components/PFrameForGraphs.js -> ../../../../sdk/model/dist/pframe_utils/columns.js -> ../../../../sdk/model/dist/components/PFrameForGraphs.js
-created dist in 4.6s
+created dist in 4s
 Build completed successfully

package/.turbo/turbo-lint.log

@@ -1,5 +1,5 @@
  WARN  Issue while reading "/home/runner/_work/platforma/platforma/.npmrc". Failed to replace env in config: ${NPMJS_TOKEN}
 
-> @milaboratories/milaboratories.ui-examples.model@1.3.22 lint /home/runner/_work/platforma/platforma/etc/blocks/ui-examples/model
+> @milaboratories/milaboratories.ui-examples.model@1.4.1 lint /home/runner/_work/platforma/platforma/etc/blocks/ui-examples/model
 > eslint .
 

package/.turbo/turbo-type-check.log

@@ -1,6 +1,6 @@
  WARN  Issue while reading "/home/runner/_work/platforma/platforma/.npmrc". Failed to replace env in config: ${NPMJS_TOKEN}
 
-> @milaboratories/milaboratories.ui-examples.model@1.3.22 type-check /home/runner/_work/platforma/platforma/etc/blocks/ui-examples/model
+> @milaboratories/milaboratories.ui-examples.model@1.4.1 type-check /home/runner/_work/platforma/platforma/etc/blocks/ui-examples/model
 > ts-builder types --target block-model
 
 ↳ tsc --noEmit --project ./tsconfig.json --customConditions ,

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @milaboratories/milaboratories.ui-examples.model
 
+## 1.4.1
+
+### Patch Changes
+
+- Updated dependencies [1e4b72a]
+  - @platforma-sdk/model@1.52.3
+
+## 1.4.0
+
+### Minor Changes
+
+- 1694d1a: Platforma API v3
+
+### Patch Changes
+
+- Updated dependencies [1694d1a]
+  - @platforma-sdk/model@1.52.0
+
 ## 1.3.22
 
 ### Patch Changes

package/dist/bundle.js

@@ -4,6 +4,86 @@
     (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';
+    /**
+     * 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 (defaults to 1)
+     * @returns A new BlockStorage instance with discriminator key
+     */
+    function createBlockStorage(initialData = {}, version = 1) {
+        return {
+            [BLOCK_STORAGE_KEY]: BLOCK_STORAGE_SCHEMA_VERSION,
+            __dataVersion: version,
+            __data: initialData,
+        };
+    }
+    // =============================================================================
+    // 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
     //
@@ -7273,28 +7353,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;
@@ -7405,8 +7476,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.9";
+    var version = "1.52.3";
 
     const PlatformaSDKVersion = version;
 
@@ -7450,7 +7542,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: {
@@ -7487,7 +7579,7 @@
         }
         argsValid(cfgOrRf) {
             if (typeof cfgOrRf === 'function') {
-                tryRegisterCallback('inputsValid', () => cfgOrRf(new RenderCtx()));
+                tryRegisterCallback('inputsValid', () => cfgOrRf(new RenderCtxLegacy()));
                 return new BlockModel({
                     ...this.config,
                     inputsValid: {
@@ -7508,7 +7600,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: {
@@ -7526,7 +7618,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: {
@@ -7536,7 +7628,7 @@
             });
         }
         subtitle(rf) {
-            tryRegisterCallback('subtitle', () => rf(new RenderCtx()));
+            tryRegisterCallback('subtitle', () => rf(new RenderCtxLegacy()));
             return new BlockModel({
                 ...this.config,
                 subtitle: {
@@ -7546,7 +7638,7 @@
             });
         }
         tags(rf) {
-            tryRegisterCallback('tags', () => rf(new RenderCtx()));
+            tryRegisterCallback('tags', () => rf(new RenderCtxLegacy()));
             return new BlockModel({
                 ...this.config,
                 tags: {
@@ -7613,7 +7705,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,
@@ -7653,6 +7748,262 @@
         }
     }
 
+    /**
+     * 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_normalize`: (rawStorage) => { storage, data }
+     * - `__pl_storage_applyUpdate`: (currentStorageJson, payload) => updatedStorageJson
+     * - `__pl_storage_getInfo`: (rawStorage) => JSON string with storage info
+     * - `__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) => UpgradeResult
+     * - `__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)) {
+            return { storage: parsed, data: getStorageData(parsed) };
+        }
+        // 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 normalize callback
+    tryRegisterCallback('__pl_storage_normalize', (rawStorage) => {
+        return normalizeStorage(rawStorage);
+    });
+    // Register apply update callback (requires existing storage)
+    tryRegisterCallback('__pl_storage_applyUpdate', (currentStorageJson, payload) => {
+        return applyStorageUpdate(currentStorageJson, payload);
+    });
+    /**
+     * Gets storage info from raw storage data.
+     * Returns structured info about the storage state.
+     *
+     * @param rawStorage - Raw data from blockStorage field (may be JSON string or object)
+     * @returns JSON string with storage info
+     */
+    function getStorageInfo(rawStorage) {
+        const { storage } = normalizeStorage(rawStorage);
+        const info = {
+            dataVersion: storage.__dataVersion,
+        };
+        return JSON.stringify(info);
+    }
+    // Register get info callback
+    tryRegisterCallback('__pl_storage_getInfo', (rawStorage) => {
+        return getStorageInfo(rawStorage);
+    });
+    /**
+     * Runs storage migration using the DataModel's upgrade 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 upgrade callback (registered by DataModel.registerCallbacks())
+        const upgradeCallback = ctx.callbackRegistry['__pl_data_upgrade'];
+        if (typeof upgradeCallback !== 'function') {
+            return { error: '__pl_data_upgrade callback not found (DataModel not registered)' };
+        }
+        // Call the migrator's upgrade function
+        let result;
+        try {
+            result = upgradeCallback({ version: currentVersion, data: currentData });
+        }
+        catch (e) {
+            const errorMsg = e instanceof Error ? e.message : String(e);
+            return { error: `upgrade() threw: ${errorMsg}` };
+        }
+        // Build info message
+        const info = result.version === currentVersion
+            ? `No migration needed (v${currentVersion})`
+            : result.warning
+                ? `Reset to initial data (v${result.version})`
+                : `Migrated v${currentVersion}→v${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 identity(x) {
         return x;
     }
@@ -8312,7 +8663,7 @@
             },
         ];
     })
-        .done(); // api version 2
+        .done(2); // api version 2
 
     exports.$BlockArgs = $BlockArgs;
     exports.ImportFileHandleSchema = ImportFileHandleSchema;