@platforma-sdk/model 1.51.9 → 1.52.0

package/src/builder.ts

@@ -1,24 +1,24 @@
-import type { BlockRenderingMode, BlockSection, AnyFunction, PlRef, BlockCodeKnownFeatureFlags, BlockConfigContainer, OutputWithStatus } from '@milaboratories/pl-model-common';
+import type { BlockRenderingMode, BlockSection, AnyFunction, PlRef, BlockCodeKnownFeatureFlags, BlockConfigContainer } from '@milaboratories/pl-model-common';
 import type { Checked, ConfigResult, TypedConfig } from './config';
 import { getImmediate } from './config';
 import { getPlatformaInstance, isInUI, tryRegisterCallback } from './internal';
 import type { Platforma, PlatformaApiVersion, PlatformaV1, PlatformaV2 } from './platforma';
-import type { InferRenderFunctionReturn, RenderFunction } from './render';
-import { RenderCtx } from './render';
+import type { InferRenderFunctionReturn, RenderFunctionLegacy } from './render';
+import { RenderCtxLegacy } from './render';
 import { PlatformaSDKVersion } from './version';
 import type {
   TypedConfigOrConfigLambda,
   ConfigRenderLambda,
   StdCtxArgsOnly,
   DeriveHref,
-  ResolveCfgType,
-  ExtractFunctionHandleReturn,
   ConfigRenderLambdaFlags,
+  InferOutputsFromConfigs,
 } from './bconfig';
 import {
   downgradeCfgOrLambda,
   isConfigLambda,
 } from './bconfig';
+import type { PlatformaExtended } from './platforma';
 
 type SectionsExpectedType = readonly BlockSection[];
 
@@ -27,12 +27,6 @@ type SectionsCfgChecked<Cfg extends TypedConfig, Args, UiState> = Checked<
   ConfigResult<Cfg, StdCtxArgsOnly<Args, UiState>> extends SectionsExpectedType ? true : false
 >;
 
-// TODO (Unused type in code)
-// type SectionsRFChecked<RF extends Function> = Checked<
-//   RF,
-//   InferRenderFunctionReturn<RF> extends SectionsExpectedType ? true : false
-// >;
-
 type InputsValidExpectedType = boolean;
 
 type InputsValidCfgChecked<Cfg extends TypedConfig, Args, UiState> = Checked<
@@ -40,12 +34,6 @@ type InputsValidCfgChecked<Cfg extends TypedConfig, Args, UiState> = Checked<
   ConfigResult<Cfg, StdCtxArgsOnly<Args, UiState>> extends InputsValidExpectedType ? true : false
 >;
 
-// TODO (Unused type in code)
-// type InputsValidRFChecked<RF extends Function> = Checked<
-//   RF,
-//   InferRenderFunctionReturn<RF> extends InputsValidExpectedType ? true : false
-// >;
-
 type NoOb = Record<string, never>;
 
 /** Main entry point that each block should use in it's "config" module. Don't forget
@@ -126,7 +114,7 @@ export class BlockModel<
    *            workflows outputs and interact with platforma drivers
    * @param flags additional flags that may alter lambda rendering procedure
    * */
-  public output<const Key extends string, const RF extends RenderFunction<Args, UiState>>(
+  public output<const Key extends string, const RF extends RenderFunctionLegacy<Args, UiState>>(
     key: Key,
     rf: RF,
     flags: ConfigRenderLambdaFlags & { withStatus: true }
@@ -144,7 +132,7 @@ export class BlockModel<
    *            workflows outputs and interact with platforma drivers
    * @param flags additional flags that may alter lambda rendering procedure
    * */
-  public output<const Key extends string, const RF extends RenderFunction<Args, UiState>>(
+  public output<const Key extends string, const RF extends RenderFunctionLegacy<Args, UiState>>(
     key: Key,
     rf: RF,
     flags?: ConfigRenderLambdaFlags
@@ -161,7 +149,7 @@ export class BlockModel<
   ): BlockModel<Args, OutputsCfg, UiState, Href> {
     if (typeof cfgOrRf === 'function') {
       const handle = `output#${key}`;
-      tryRegisterCallback(handle, () => cfgOrRf(new RenderCtx()));
+      tryRegisterCallback(handle, () => cfgOrRf(new RenderCtxLegacy()));
       return new BlockModel({
         ...this.config,
         outputs: {
@@ -185,7 +173,7 @@ export class BlockModel<
   }
 
   /** Shortcut for {@link output} with retentive flag set to true. */
-  public retentiveOutput<const Key extends string, const RF extends RenderFunction<Args, UiState>>(
+  public retentiveOutput<const Key extends string, const RF extends RenderFunctionLegacy<Args, UiState>>(
     key: Key,
     rf: RF,
   ) {
@@ -193,7 +181,7 @@ export class BlockModel<
   }
 
   /** Shortcut for {@link output} with withStatus flag set to true. */
-  public outputWithStatus<const Key extends string, const RF extends RenderFunction<Args, UiState>>(
+  public outputWithStatus<const Key extends string, const RF extends RenderFunctionLegacy<Args, UiState>>(
     key: Key,
     rf: RF,
   ) {
@@ -201,7 +189,7 @@ export class BlockModel<
   }
 
   /** Shortcut for {@link output} with retentive and withStatus flags set to true. */
-  public retentiveOutputWithStatus<const Key extends string, const RF extends RenderFunction<Args, UiState>>(
+  public retentiveOutputWithStatus<const Key extends string, const RF extends RenderFunctionLegacy<Args, UiState>>(
     key: Key,
     rf: RF,
   ) {
@@ -214,14 +202,14 @@ export class BlockModel<
     cfg: Cfg & InputsValidCfgChecked<Cfg, Args, UiState>
   ): BlockModel<Args, OutputsCfg, UiState, Href>;
   /** Sets custom configuration predicate on the block args at which block can be executed */
-  public argsValid<RF extends RenderFunction<Args, UiState, boolean>>(
+  public argsValid<RF extends RenderFunctionLegacy<Args, UiState, boolean>>(
     rf: RF
   ): BlockModel<Args, OutputsCfg, UiState, Href>;
   public argsValid(
     cfgOrRf: TypedConfig | AnyFunction,
   ): BlockModel<Args, OutputsCfg, UiState, `/${string}`> {
     if (typeof cfgOrRf === 'function') {
-      tryRegisterCallback('inputsValid', () => cfgOrRf(new RenderCtx()));
+      tryRegisterCallback('inputsValid', () => cfgOrRf(new RenderCtxLegacy()));
       return new BlockModel<Args, OutputsCfg, UiState>({
         ...this.config,
         inputsValid: {
@@ -245,7 +233,7 @@ export class BlockModel<
   /** Sets the config to generate list of section in the left block overviews panel */
   public sections<
     const Ret extends SectionsExpectedType,
-    const RF extends RenderFunction<Args, UiState, Ret>,
+    const RF extends RenderFunctionLegacy<Args, UiState, Ret>,
   >(rf: RF): BlockModel<Args, OutputsCfg, UiState, DeriveHref<ReturnType<RF>>>;
   public sections<const Cfg extends TypedConfig>(
     cfg: Cfg & SectionsCfgChecked<Cfg, Args, UiState>
@@ -261,7 +249,7 @@ export class BlockModel<
     if (Array.isArray(arrOrCfgOrRf)) {
       return this.sections(getImmediate(arrOrCfgOrRf));
     } else if (typeof arrOrCfgOrRf === 'function') {
-      tryRegisterCallback('sections', () => arrOrCfgOrRf(new RenderCtx()));
+      tryRegisterCallback('sections', () => arrOrCfgOrRf(new RenderCtxLegacy()));
       return new BlockModel<Args, OutputsCfg, UiState>({
         ...this.config,
         sections: {
@@ -279,9 +267,9 @@ export class BlockModel<
 
   /** Sets a rendering function to derive block title, shown for the block in the left blocks-overview panel. */
   public title(
-    rf: RenderFunction<Args, UiState, string>,
+    rf: RenderFunctionLegacy<Args, UiState, string>,
   ): BlockModel<Args, OutputsCfg, UiState, Href> {
-    tryRegisterCallback('title', () => rf(new RenderCtx()));
+    tryRegisterCallback('title', () => rf(new RenderCtxLegacy()));
     return new BlockModel<Args, OutputsCfg, UiState, Href>({
       ...this.config,
       title: {
@@ -292,9 +280,9 @@ export class BlockModel<
   }
 
   public subtitle(
-    rf: RenderFunction<Args, UiState, string>,
+    rf: RenderFunctionLegacy<Args, UiState, string>,
   ): BlockModel<Args, OutputsCfg, UiState, Href> {
-    tryRegisterCallback('subtitle', () => rf(new RenderCtx()));
+    tryRegisterCallback('subtitle', () => rf(new RenderCtxLegacy()));
     return new BlockModel<Args, OutputsCfg, UiState, Href>({
       ...this.config,
       subtitle: {
@@ -305,9 +293,9 @@ export class BlockModel<
   }
 
   public tags(
-    rf: RenderFunction<Args, UiState, string[]>,
+    rf: RenderFunctionLegacy<Args, UiState, string[]>,
   ): BlockModel<Args, OutputsCfg, UiState, Href> {
-    tryRegisterCallback('tags', () => rf(new RenderCtx()));
+    tryRegisterCallback('tags', () => rf(new RenderCtxLegacy()));
     return new BlockModel<Args, OutputsCfg, UiState, Href>({
       ...this.config,
       tags: {
@@ -407,7 +395,10 @@ export class BlockModel<
     if (this.config.initialArgs === undefined) throw new Error('Initial arguments not set.');
 
     const config: BlockConfigContainer = {
+      v4: undefined,
       v3: {
+        configVersion: 3,
+        modelAPIVersion: 1,
         sdkVersion: PlatformaSDKVersion,
         renderingMode: this.config.renderingMode,
         initialArgs: this.config.initialArgs,
@@ -452,29 +443,3 @@ export class BlockModel<
     };
   }
 }
-
-export type InferOutputType<CfgOrFH, Args, UiState> = CfgOrFH extends TypedConfig
-  ? ResolveCfgType<CfgOrFH, Args, UiState>
-  : CfgOrFH extends ConfigRenderLambda
-    ? ExtractFunctionHandleReturn<CfgOrFH>
-    : never;
-
-type InferOutputsFromConfigs<
-  Args,
-  OutputsCfg extends Record<string, TypedConfigOrConfigLambda>,
-  UiState,
-> = {
-  [Key in keyof OutputsCfg]:
-    & OutputWithStatus<InferOutputType<OutputsCfg[Key], Args, UiState>>
-    & { __unwrap: (OutputsCfg[Key] extends { withStatus: true } ? false : true) };
-};
-
-export type PlatformaExtended<Pl extends Platforma = Platforma> = Pl & {
-  blockModelInfo: BlockModelInfo;
-};
-
-export type BlockModelInfo = {
-  outputs: Record<string, {
-    withStatus: boolean;
-  }>;
-};

package/src/components/PlDataTable.ts

@@ -35,6 +35,7 @@ import type {
   ColumnProvider,
   PColumnDataUniversal,
   RenderCtx,
+  RenderCtxLegacy,
   TreeNodeAccessor,
 } from '../render';
 import {
@@ -631,7 +632,7 @@ export function isColumnOptional(spec: { annotations?: Annotation }): boolean {
  * @returns PlAgDataTableV2 table source
  */
 export function createPlDataTableV2<A, U>(
-  ctx: RenderCtx<A, U>,
+  ctx: RenderCtx<A, U> | RenderCtxLegacy<A, U>,
   columns: PColumn<PColumnDataUniversal>[],
   tableState: PlDataTableStateV2 | undefined,
   ops?: CreatePlDataTableOps,

package/src/index.ts

@@ -1,6 +1,9 @@
 export * from './block_state_patch';
 export * from './block_state_util';
+export * from './block_storage';
 export * from './builder';
+export { BlockModelV3 } from './block_model';
+export { DataModel } from './block_migrations';
 export * from './bconfig';
 export * from './components';
 export * from './config';

package/src/internal.ts

@@ -2,6 +2,7 @@ import type { OutputWithStatus } from '@milaboratories/pl-model-common';
 import { } from './global';
 import type { Platforma, PlatformaApiVersion } from './platforma';
 import type { FutureHandle, GlobalCfgRenderCtx } from './render/internal';
+import type { ConfigRenderLambda, ConfigRenderLambdaFlags } from './bconfig';
 
 /** Utility code helping to identify whether the code is running in actual UI environment */
 export function isInUI() {
@@ -41,6 +42,56 @@ export function tryRegisterCallback(key: string, callback: (...args: any[]) => a
   return true;
 }
 
+/**
+ * Registers a callback, replacing any existing callback with the same key.
+ * Use this for callbacks that have a default value but can be overridden.
+ *
+ * @param key - The callback registry key
+ * @param callback - The callback function to register
+ * @returns true if registered, false if not in render context
+ */
+export function replaceCallback(key: string, callback: (...args: any[]) => any): boolean {
+  const ctx = tryGetCfgRenderCtx();
+  if (ctx === undefined) return false;
+  ctx.callbackRegistry[key] = callback;
+  return true;
+}
+
+//
+// ConfigRenderLambda helpers
+//
+
+/** Options for creating a ConfigRenderLambda descriptor */
+export type CreateLambdaOptions = ConfigRenderLambdaFlags & {
+  /** The callback registry key */
+  handle: string;
+};
+
+/** Creates a ConfigRenderLambda descriptor without registering a callback. */
+export function createRenderLambda<T = unknown>(opts: CreateLambdaOptions): ConfigRenderLambda<T> {
+  const { handle, ...flags } = opts;
+  return {
+    __renderLambda: true,
+    handle,
+    ...flags,
+  } as ConfigRenderLambda<T>;
+}
+
+/** Registers a callback and returns a ConfigRenderLambda descriptor. */
+export function createAndRegisterRenderLambda<T = unknown>(opts: CreateLambdaOptions & {
+  lambda: (...args: any[]) => any;
+}, replace?: boolean): ConfigRenderLambda<T> {
+  const { handle, lambda, ...flags } = opts;
+
+  if (replace) {
+    replaceCallback(handle, lambda);
+  } else {
+    tryRegisterCallback(handle, lambda);
+  }
+
+  return createRenderLambda<T>({ handle, ...flags });
+}
+
 const futureResolves = new Map<string, ((value: unknown) => void)[]>();
 
 export function registerFutureAwait(handle: FutureHandle, onResolve: (value: unknown) => void) {

package/src/platforma.ts

@@ -1,6 +1,7 @@
 import type { BlockApiV1 } from './block_api_v1';
 import type { BlockApiV2 } from './block_api_v2';
-import type { BlockOutputsBase, BlockState, DriverKit, OutputWithStatus } from '@milaboratories/pl-model-common';
+import type { BlockApiV3 } from './block_api_v3';
+import type { BlockOutputsBase, BlockStateV3, DriverKit, OutputWithStatus } from '@milaboratories/pl-model-common';
 import type { SdkInfo } from './sdk_info';
 import type { BlockStatePatch } from './block_state_patch';
 
@@ -30,12 +31,34 @@ export interface PlatformaV2<
   readonly apiVersion: 2;
 }
 
+export interface PlatformaV3<
+  Args = unknown,
+  Outputs extends Record<string, OutputWithStatus<unknown>> = Record<string, OutputWithStatus<unknown>>,
+  Data = unknown,
+  Href extends `/${string}` = `/${string}`,
+> extends BlockApiV3<Args, Outputs, Data, Href>,
+  DriverKit {
+  /** Information about SDK version current platforma environment was compiled with. */
+  readonly sdkInfo: SdkInfo;
+  readonly apiVersion: 3;
+}
+
 export type Platforma<
   Args = unknown,
   Outputs extends Record<string, OutputWithStatus<unknown>> = Record<string, OutputWithStatus<unknown>>,
   UiState = unknown,
   Href extends `/${string}` = `/${string}`,
-> = PlatformaV1<Args, Outputs, UiState, Href> | PlatformaV2<Args, Outputs, UiState, Href>;
+> = PlatformaV1<Args, Outputs, UiState, Href> | PlatformaV2<Args, Outputs, UiState, Href> | PlatformaV3<Args, Outputs, UiState, Href>;
+
+export type PlatformaExtended<Pl extends Platforma = Platforma> = Pl & {
+  blockModelInfo: BlockModelInfo;
+};
+
+export type BlockModelInfo = {
+  outputs: Record<string, {
+    withStatus: boolean;
+  }>;
+};
 
 export type PlatformaApiVersion = Platforma['apiVersion'];
 
@@ -49,15 +72,18 @@ export type InferUiState<Pl extends Platforma> =
     ? UiState
     : never;
 
+export type InferDataType<Pl extends Platforma> =
+  Pl extends Platforma<unknown, Record<string, OutputWithStatus<unknown>>, infer Data>
+    ? Data
+    : never;
+
 export type InferHrefType<Pl extends Platforma> =
   Pl extends Platforma<unknown, BlockOutputsBase, unknown, infer Href> ? Href : never;
 
 export type PlatformaFactory = (config: { sdkVersion: string }) => Platforma;
 
-export type InferBlockState<Pl extends Platforma> = BlockState<
-  InferArgsType<Pl>,
+export type InferBlockState<Pl extends Platforma> = BlockStateV3<
   InferOutputsType<Pl>,
-  InferUiState<Pl>,
   InferHrefType<Pl>
 >;
 

package/src/render/api.ts

@@ -515,33 +515,22 @@ export class ResultPool implements ColumnProvider, AxisLabelProvider {
 }
 
 /** Main entry point to the API available within model lambdas (like outputs, sections, etc..) */
-export class RenderCtx<Args, UiState> {
-  private readonly ctx: GlobalCfgRenderCtx;
+export abstract class RenderCtxBase<Args, Data> {
+  protected readonly ctx: GlobalCfgRenderCtx;
 
   constructor() {
     this.ctx = getCfgRenderCtx();
   }
 
-  private _argsCache?: { v: Args };
-
-  public get args(): 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;
-  }
-
-  private _uiStateCache?: { v: UiState };
+  private _dataCache?: { v: Data };
 
-  public get uiState(): UiState {
-    if (this._uiStateCache === undefined) {
-      const raw = this.ctx.uiState;
+  public get data(): Data {
+    if (this._dataCache === undefined) {
+      const raw = this.ctx.data;
       const value = typeof raw === 'function' ? raw() : raw;
-      this._uiStateCache = { v: value ? JSON.parse(value) : ({} as UiState) };
+      this._dataCache = { v: value ? JSON.parse(value) : ({} as Data) };
     }
-    return this._uiStateCache.v;
+    return this._dataCache.v;
   }
 
   // lazy rendering because this feature is rarely used
@@ -691,8 +680,50 @@ export class RenderCtx<Args, UiState> {
   }
 }
 
-export type RenderFunction<Args = unknown, UiState = unknown, Ret = unknown> = (
-  rCtx: RenderCtx<Args, UiState>
+/** Main entry point to the API available within model lambdas (like outputs, sections, etc..) for v3+ blocks */
+export class RenderCtx<Args, Data> extends RenderCtxBase<Args, Data> {
+  private _argsCache?: { v: Args | undefined };
+  public get args(): Args | undefined {
+    if (this._argsCache === undefined) {
+      const raw = this.ctx.args;
+      const value = typeof raw === 'function' ? raw() : raw;
+      // args can be undefined when derivation fails (e.g., validation error in args())
+      this._argsCache = { v: value === undefined ? undefined : JSON.parse(value) };
+    }
+    return this._argsCache.v;
+  }
+}
+
+/** Render context for legacy v1/v2 blocks - provides backward compatibility */
+export class RenderCtxLegacy<Args, UiState> extends RenderCtxBase<Args, UiState> {
+  private _argsCache?: { v: Args };
+  public get args(): 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;
+  }
+
+  private _uiStateCache?: { v: UiState };
+
+  public get uiState(): UiState {
+    if (this._uiStateCache === undefined) {
+      const raw = this.ctx.uiState!;
+      const value = typeof raw === 'function' ? raw() : raw;
+      this._uiStateCache = { v: value ? JSON.parse(value) : ({} as UiState) };
+    }
+    return this._uiStateCache.v;
+  }
+}
+
+export type RenderFunction<Args = unknown, State = unknown, Ret = unknown> = (
+  rCtx: RenderCtx<Args, State>
+) => Ret;
+
+export type RenderFunctionLegacy<Args = unknown, State = unknown, Ret = unknown> = (
+  rCtx: RenderCtxLegacy<Args, State>
 ) => Ret;
 
 export type UnwrapFutureRef<K> =

package/src/render/internal.ts

@@ -183,7 +183,9 @@ export interface GlobalCfgRenderCtx extends GlobalCfgRenderCtxMethods {
   //
 
   readonly args: string | (() => string);
-  readonly uiState: string | (() => string);
+  /** @deprecated Use `data` instead. Optional for backward compatibility - falls back to `data` if not injected. */
+  readonly uiState?: string | (() => string);
+  readonly data: string | (() => string);
   readonly activeArgs: undefined | string | (() => string | undefined);
 
   // Note: strings below are used because, anyway, using strings is the only way