import { BlockKind, DataModel } from "./block_migrations.js"; import { ConfigRenderLambda, ConfigRenderLambdaFlags, InferOutputsFromLambdas } from "./bconfig/lambdas.js"; import { DeriveHref } from "./bconfig/util.js"; import "./bconfig/index.js"; import { BlockDefaultUiServices } from "./services/service_resolve.js"; import { InferRenderFunctionReturn, RenderCtxBase, RenderFunction } from "./render/api.js"; import "./render/index.js"; import { PluginData, PluginInstance, PluginModel, PluginOutputs, PluginParams, PluginPublicOutputs } from "./plugin_model.js"; import { PlatformaExtended, PlatformaV3 } from "./platforma.js"; import { ArgsIssue, BlockCodeKnownFeatureFlags, BlockSection, PlRef } from "@milaboratories/pl-model-common"; type SectionsExpectedType = readonly BlockSection[]; type NoOb = Record; /** * Per-property lambdas for deriving plugin params from block render context. * Each property is a function that receives the block's RenderCtxBase and returns the param value. */ export type ParamsInput = { [K in keyof Params]: (ctx: RenderCtxBase) => Params[K]; }; /** * Type-erased version of ParamsInput for internal storage. */ type ParamsInputErased = Record unknown>; /** * Plugin record: model + param derivation lambdas. */ export type PluginRecord = { readonly model: PluginModel; readonly inputs: ParamsInputErased; }; /** Main entry point that each block should use in it's "config" module. Don't forget * to call {@link done()} at the end of configuration. Value returned by this builder must be * exported as constant with name "platforma" from the "config" module. * API version is 3 (for UI) and 2 (for model) */ export declare class BlockModelV3, Data extends Record = Record, Href extends `/${string}` = "/", Plugins extends Record = {}, Transfers extends Record = {}, Params = unknown, PrerunArgs = unknown> { private readonly config; private constructor(); static readonly FEATURE_FLAGS: { requiresPFrameSpec: true; requiresPFrame: true; requiresDialog: true; requiresColumnsCollection: true; supportsLazyState: true; supportsPframeQueryRanking: true; supportsColumnLinks: true; requiresUIAPIVersion: number; requiresModelAPIVersion: number; requiresCreatePTable: number; requiresPFramesVersion: number; requiresArgsIssues: true; }; /** @deprecated Use FEATURE_FLAGS */ static readonly INITIAL_BLOCK_FEATURE_FLAGS: { requiresPFrameSpec: true; requiresPFrame: true; requiresDialog: true; requiresColumnsCollection: true; supportsLazyState: true; supportsPframeQueryRanking: true; supportsColumnLinks: true; requiresUIAPIVersion: number; requiresModelAPIVersion: number; requiresCreatePTable: number; requiresPFramesVersion: number; requiresArgsIssues: true; }; /** * Creates a new BlockModelV3 builder bound to a data model and a block kind. * * The `kind` argument is cross-checked against the kind handed to the * builder: its `Params` type must match at compile time (via * `BlockKind`), and its reference value must match at runtime. The * reference is baked into the config so the published manifest can advertise * which kind the block implements. * * @example * const dataModel = new DataModelBuilder({ kind }) * .from("v1") * .init(({ params }) => params ?? { numbers: [], labels: [] }); * * BlockModelV3.create({ dataModel, kind }) * .args((data) => ({ numbers: data.numbers })) * .sections(() => [{ type: 'link', href: '/', label: 'Main' }]) * .done(); */ static create, Params = never, Transfers extends Record = {}>(args: { dataModel: DataModel; kind: BlockKind; }): BlockModelV3; /** * Add output cell wrapped with additional status information to the configuration * * @param key output cell name, that can be later used to retrieve the rendered value * @param rf callback calculating output value using context, that allows to access * workflows outputs and interact with platforma drivers * @param flags additional flags that may alter lambda rendering procedure * */ output>(key: Key, rf: RF, flags: ConfigRenderLambdaFlags & { withStatus: true; }): BlockModelV3> & { withStatus: true; }; }, Data, Href, Plugins, Transfers, Params, PrerunArgs>; /** * Add output cell to the configuration * * @param key output cell name, that can be later used to retrieve the rendered value * @param rf callback calculating output value using context, that allows to access * workflows outputs and interact with platforma drivers * @param flags additional flags that may alter lambda rendering procedure * */ output>(key: Key, rf: RF, flags?: ConfigRenderLambdaFlags): BlockModelV3>; }, Data, Href, Plugins, Transfers, Params, PrerunArgs>; /** Shortcut for {@link output} with retentive flag set to true. */ retentiveOutput>(key: Key, rf: RF): BlockModelV3>; }, Data, Href, Plugins, Transfers, Params, PrerunArgs>; /** Shortcut for {@link output} with withStatus flag set to true. */ outputWithStatus>(key: Key, rf: RF): BlockModelV3> & { withStatus: true; }; }, Data, Href, Plugins, Transfers, Params, PrerunArgs>; /** * Sets a function to derive block args from data. * This is called during setData to compute the args that will be used for block execution. * * Build args even from incomplete data, and say what keeps the block from running in * {@link argsIssues}: args that exist let the platform see what the block references * before it is ready to run. Throwing here still works, and means there are no args at all. * * Setting args again drops a {@link argsIssues} set before, since it checked other args. * * @example * .args((data) => ({ numbers: data.numbers })) * * @example * .args((data) => ({ numbers: data.numbers })) * .argsIssues(({ args }) => * args.numbers.length === 0 ? [{ severity: 'error', message: 'Numbers required' }] : [], * ) */ args(lambda: (data: Data) => A): BlockModelV3; /** * Sets a function that finds what keeps the block from running with the args {@link args} * derived (optional). It is called after `args()`, with its result and the data it was built * from. * * An issue of severity `"error"` keeps the block from running; a `"warning"` does not. A throw, * or a result that is not a list of issues, counts as one error carrying the thrown or parser * message. Without this function, args that `args()` returns are always runnable. * * A block without its own {@link prerunArgs} is staged with its args, and only while this * function finds no errors in them. * * Must be set after `.args()`, and is dropped when `.args()` is set again. * * @example * .args((data) => ({ dataset: data.dataset, threshold: data.threshold })) * .argsIssues(({ args }) => { * const issues: ArgsIssue[] = []; * if (args.dataset === undefined) issues.push({ severity: 'error', message: 'Select a dataset' }); * if (args.threshold > 0.5) issues.push({ severity: 'warning', message: 'Threshold is high' }); * return issues; * }) */ argsIssues(fn: (input: { args: Args; data: Data; }) => ArgsIssue[]): BlockModelV3; /** * Sets a function to derive pre-run args from data (optional). * This is called during setData to compute the args that will be used for staging/pre-run phase. * * If not defined, defaults to using the args() function result. * If defined, uses its return value for the staging / prerun phase. * * The staging / prerun phase runs only if currentPrerunArgs differs from the executed * version of prerunArgs (same comparison logic as currentArgs vs prodArgs). * * Setting prerun args again drops a {@link prerunArgsIssues} set before, since it checked other * args. * * @example * .prerunArgs((data) => ({ numbers: data.numbers })) * * @example * .prerunArgs((data) => { * // Return undefined to skip staging for this block * if (!data.isReady) return undefined; * return { numbers: data.numbers }; * }) */ prerunArgs

(fn: (data: Data) => P): BlockModelV3; /** * Sets a function that finds what keeps the block from being staged with the args * {@link prerunArgs} derived (optional). It is called after `prerunArgs()`, with its result * and the data it was built from; not when `prerunArgs()` returned `undefined`, which skips * staging anyway. * * An issue of severity `"error"` keeps the block from being staged; a `"warning"` does not. A * throw, or a result that is not a list of issues, counts as one error carrying the thrown or * parser message. {@link argsIssues} is not consulted for a block with its own prerun args. * * Must be set after `.prerunArgs()`, and is dropped when `.prerunArgs()` is set again. * * @example * .prerunArgs((data) => ({ dataset: data.dataset })) * .prerunArgsIssues(({ prerunArgs }) => * prerunArgs.dataset === undefined ? [{ severity: 'error', message: 'Select a dataset' }] : [], * ) */ prerunArgsIssues(fn: (input: { prerunArgs: Exclude; data: Data; }) => ArgsIssue[]): BlockModelV3; /** * Sets the function that projects block data back to this kind's params, for * exporting the project as a template. * * The inverse of the data model's `init`: `init` builds data from `params`, this * recovers the `params` that would rebuild the current data. Return only params * — runtime and derived state is dropped, and the exporter supplies the rest of * the entry (`id`, `kind`), which this lambda cannot set. * * References are returned as ordinary `PlRef`s; the SDK rewrites them into * template-local form on the way out, so a block never deals with the file * representation. * * Required: `done()` throws without it. A block whose state cannot be reduced to * params returns `{}` and says so explicitly, rather than exporting an entry with * no params that silently applies as a default-initialized block. * * The return type is the kind's `Params`, so a block whose projection drifts * from its own init contract fails to compile. Available only on a * kind-carrying model — `create(dataModel)` without a kind leaves `Params` as * `unknown` and this method cannot be type-checked against anything. * * @example * BlockModelV3.create({ dataModel, kind }) * .args((data) => ({ numbers: data.numbers })) * .templateParams((data) => ({ sources: data.sources })) * .done(); */ templateParams(fn: (data: Data) => Params): BlockModelV3; /** Sets the lambda to generate list of sections in the left block overviews panel. */ sections>(rf: RF): BlockModelV3>, Plugins, Transfers, Params, PrerunArgs>; /** Sets a rendering function to derive block title, shown for the block in the left blocks-overview panel. */ title(rf: RenderFunction): BlockModelV3; /** * Sets a rendering function to derive block subtitle, shown below the title in the left * blocks-overview panel. Unlike the title, it can read the result pool, so it can name the * inputs the block reads (e.g. through `ctx.resultPool.getPColumnSpecByRef`). */ subtitle(rf: RenderFunction): BlockModelV3; tags(rf: RenderFunction): BlockModelV3; /** Sets or overrides feature flags for the block. */ withFeatureFlags(flags: Partial): BlockModelV3; /** * Defines how to derive list of upstream references this block is meant to enrich with its exports from block args. * Influences dependency graph construction. */ enriches(lambda: (args: Args) => PlRef[]): BlockModelV3; /** * Registers a plugin instance with the block. * Consumes a transfer if one was defined for this plugin ID in the migration chain. * * Type checks: * - If Transfers[Id] exists, verifies it extends PTransferData (transfer type compatibility) * - If no Transfers[Id], rejects plugins with transferAt set (missing .transfer() in data model) * - Rejects duplicate plugin IDs (Id already in keyof Plugins) * * @param instance - PluginInstance created via factory.create({ pluginId, ... }) * @param params - Per-property lambdas deriving plugin params from block RenderCtx * * @example * .plugin(mainTable, { * columns: (ctx) => ctx.outputs?.resolve("data")?.getPColumns(), * sourceId: (ctx) => ctx.data.selectedSource, * }) */ plugin(instance: PluginInstance, params?: ParamsInput): BlockModelV3; }, Omit, Params, PrerunArgs>; /** Renders all provided block settings into a pre-configured platforma API * instance, that can be used in frontend to interact with block data, and * other features provided by the platforma to the block. * * Type-level check: if there are unconsumed transfers (from `.transfer()` calls * in the migration chain), this method requires an impossible `never` argument, * producing a compile error. Register all transferred plugins via `.plugin(instance)` * before calling `.done()`. */ done(..._: keyof Transfers extends never ? [] : [never]): PlatformaExtended, Href, Plugins, BlockDefaultUiServices>>; } export {}; //# sourceMappingURL=block_model.d.ts.map