import { PluginFactoryLike } from "./plugin_handle.js"; import { DataModel, DataRecoverFn, DataVersioned, TransferTarget } from "./block_migrations.js"; import { PluginName } from "./block_storage.js"; import { ResolveModelServices, ResolveUiServices } from "./services/service_resolve.js"; import { PluginRenderCtx } from "./render/api.js"; import "./render/index.js"; import { BlockCodeKnownFeatureFlags, OutputWithStatus } from "@milaboratories/pl-model-common"; /** Symbol for internal builder creation method */ declare const FROM_BUILDER: unique symbol; /** Output function signature for plugin render context. */ type PluginOutputFn = (ctx: PluginRenderCtx, ModelServices, UiServices>>) => T; /** Mapped output functions for a plugin's outputs. */ type PluginOutputFns = { [K in keyof Outputs]: PluginOutputFn; }; /** Internal plugin↔block handshake. `Symbol.for` (not `Symbol`) so it stays * identical across multiple `@platforma-sdk/model` copies in one process. */ export declare const CREATE_PLUGIN_MODEL: unique symbol; /** * Runtime definition for a single public output field. * Stored in PluginModel and passed through BlockModelInfo to the UI layer. */ export type PublicOutputFieldDef = { readonly getter: (data: unknown) => unknown; }; export type PublicOutputDef = { [K in keyof PublicOutputs]: PublicOutputFieldDef; }; export type PluginData = Record; export type PluginParams = undefined | Record; export type PluginOutputs = Record; export type PluginPublicOutputs = Record; export type PluginConfig = undefined | Record; /** * Plugin data model with typed migration chain and config-aware initialization. * * @typeParam Data - Current (latest) plugin data type * @typeParam Versions - Map of version keys to their data types (accumulated by the chain) * @typeParam Config - Config type passed to init function (undefined if none) */ export declare class PluginDataModel = {}, Config = undefined> { readonly dataModel: DataModel; private readonly configInitFn; /** @internal Phantom field to anchor the Versions type parameter. */ readonly __versions?: Versions; private constructor(); /** @internal */ static [FROM_BUILDER], Config>(dataModel: DataModel, configInitFn: (config?: Config) => Data): PluginDataModel; /** Create fresh data with optional config. */ getDefaultData(config?: Config): DataVersioned; } /** Internal state for plugin data model chain. */ type PluginChainState = { initialVersion: string; migrations: Array<{ toVersion: string; fn: (data: unknown) => unknown; }>; recoverFn?: (version: string, data: unknown) => unknown; recoverAtIndex?: number; }; /** Version → persisted data shape for each migration step (third generic of `PluginModel.define` when `data` is a `PluginDataModel`). */ export type PluginDataModelVersions, unknown>> = M extends PluginDataModel ? Versions : never; /** * Builder for creating PluginDataModel with type-safe migrations. * Mirrors DataModelBuilder — same .from(), .migrate(), .recover(), .init() chain. * * @example * const pluginData = new PluginDataModelBuilder() * .from("v1") * .migrate("v2", (v1) => ({ ...v1, filters: [] })) * .init((config?) => ({ * state: createDefaultState(config?.ops), * filters: [], * })); */ export declare class PluginDataModelBuilder { from(version: V): PluginDataModelInitialChain>; } /** * Chain returned by .migrate(). Supports .migrate(), .recover(), .init(). * No .upgradeLegacy() — that is only available on the initial chain. */ export declare class PluginDataModelChain> { protected readonly state: PluginChainState; protected constructor(state: PluginChainState); /** @internal */ static [FROM_BUILDER]>(state: PluginChainState): PluginDataModelChain; /** * Add a migration step transforming data from the current version to the next. */ migrate(version: NextV, fn: (current: Data) => Next): PluginDataModelChain>; /** * Set a recovery handler for unknown or legacy versions. * Can only be called once — the returned chain has no recover() method. */ recover(fn: DataRecoverFn): PluginDataModelWithRecover; /** Finalize the PluginDataModel. */ init(fn: (config?: Config) => Data): PluginDataModel; } /** * Initial chain returned by new PluginDataModelBuilder().from(). * Extends PluginDataModelChain with .upgradeLegacy() — available only before * any .migrate() calls, matching the block's DataModelInitialChain pattern. */ export declare class PluginDataModelInitialChain> extends PluginDataModelChain { /** @internal */ static [FROM_BUILDER]>(state: PluginChainState): PluginDataModelInitialChain; /** * Handle data from a previous plugin type occupying this slot. * Prepends a migration from DATA_MODEL_LEGACY_VERSION to the initial version. * When a plugin type changes, the old data arrives with DATA_MODEL_LEGACY_VERSION — * this function transforms it into the initial version, then the normal chain runs. * * Must be called right after .from() — not available after .migrate(). * Mutually exclusive with recover(). * * @param fn - Transform from old plugin's raw data to this plugin's initial data type */ upgradeLegacy(fn: (data: unknown) => Data): PluginDataModelWithRecover; } /** * Chain after .recover() — supports .migrate(), .init(). No second recover(). */ export declare class PluginDataModelWithRecover> { private readonly state; private constructor(); /** @internal */ static [FROM_BUILDER]>(state: PluginChainState): PluginDataModelWithRecover; migrate(version: NextV, fn: (current: Data) => Next): PluginDataModelWithRecover>; init(fn: (config?: Config) => Data): PluginDataModel; } /** * A named plugin instance created by `factory.create({ pluginId, ... })`. * Passed to both `.transfer()` (on migration chain) and `.plugin()` (on BlockModelV3). * Implements TransferTarget so the migration chain can accept it. * * @typeParam Id - Plugin instance ID literal type * @typeParam Data - Plugin data type * @typeParam Params - Plugin params type * @typeParam Outputs - Plugin outputs type * @typeParam TransferData - Type of data entering the plugin via transfer (never if no transfer) */ export declare class PluginInstance implements TransferTarget { readonly id: Id; readonly transferVersion: string; /** @internal Phantom for type inference; never set at runtime. */ readonly __instanceTypes?: { data: Data; params: Params; outputs: Outputs; modelServices: ModelServices; uiServices: UiServices; publicOutputs: PublicOutputs; }; /** Bound closure that creates the PluginModel. Config is captured at factory.create() time. */ private readonly createPluginModel; private constructor(); /** @internal Accepts concrete Config — binds it into a closure, avoiding Config variance issues. */ static [FROM_BUILDER](id: Id, factory: PluginModelFactory, ModelServices, UiServices>, transferVersion: string, config?: Config): PluginInstance; /** @internal Create a PluginModel from this instance. Used by BlockModelV3.plugin(). */ [CREATE_PLUGIN_MODEL](): PluginModel; } /** * Configured plugin instance returned by PluginModelFactory[CREATE_PLUGIN_MODEL](). * Contains the plugin's name, data model, and output definitions. */ export declare class PluginModel { /** Globally unique plugin name */ readonly name: PluginName; /** Data model instance for this plugin */ readonly dataModel: DataModel; /** Output definitions - functions that compute outputs from plugin context */ readonly outputs: PluginOutputFns; /** Feature flags declared by this plugin */ readonly featureFlags?: BlockCodeKnownFeatureFlags; /** Create fresh default data. Config (if any) is captured at creation time. */ readonly getDefaultData: () => DataVersioned; /** Public output definitions — accessible without usePlugin() via app.plugins */ readonly publicOutputDef: PublicOutputDef; private constructor(); /** * Internal method for creating PluginModel from factory. * Uses Symbol key to prevent external access. * @internal */ static [FROM_BUILDER](options: { name: PluginName; dataModel: DataModel; outputs: PluginOutputFns; featureFlags?: BlockCodeKnownFeatureFlags; getDefaultData: () => DataVersioned; publicOutputDef: PublicOutputDef; }): PluginModel; /** * Creates a new PluginModelBuilder with a PluginDataModel (supports transfer / config). * * @example * const pluginData = new PluginDataModelBuilder().from("v1") * .migrate("v2", (v1) => ({ ...v1, filters: [] })) * .init((config?) => ({ * state: createDefaultState(config?.ops), * filters: [], * })); * * const myPlugin = PluginModel.define({ * name: 'myPlugin' as PluginName, * data: pluginData, * }).build(); */ static define = {}, Config extends PluginConfig = undefined, Flags extends BlockCodeKnownFeatureFlags = {}>(options: { name: PluginName; data: PluginDataModel; featureFlags?: Flags; }): PluginModelInitialBuilder, ResolveUiServices>; /** * Creates a new PluginModelBuilder with a data model factory function (backward compatible). * * @example * const myPlugin = PluginModel.define({ * name: 'myPlugin' as PluginName, * data: (cfg) => dataModelChain.init(() => ({ value: cfg.defaultValue })), * }).build(); */ static define(options: { name: PluginName; data: (config?: Config) => DataModel; featureFlags?: Flags; }): PluginModelInitialBuilder, ResolveUiServices>; } /** Plugin factory returned by PluginModelBuilder.build(). */ export interface PluginFactory = {}, ModelServices = {}, UiServices = {}> extends PluginFactoryLike { /** Create a named plugin instance, optionally with transfer at a specific version. */ create(options: { pluginId: Id; transferAt?: V; config?: Config; }): PluginInstance; /** Public output field definitions declared via .publicOutput(). */ readonly publicOutputDef: PublicOutputDef; /** * @internal Phantom field for structural type extraction. * Enables InferFactoryData/InferFactoryOutputs to work via PluginFactoryLike. */ readonly __types?: { data: Data; params: Params; outputs: Outputs; modelServices: ModelServices; uiServices: UiServices; config: Config; versions: Versions; publicOutputs: PublicOutputs; }; } declare class PluginModelFactory = {}, ModelServices = {}, UiServices = {}> implements PluginFactory { private readonly name; private readonly dataFn; private readonly getDefaultDataFn?; readonly outputs: PluginOutputFns; private readonly featureFlags?; readonly publicOutputDef: PublicOutputDef; private constructor(); /** @internal */ static [FROM_BUILDER] = {}, ModelServices = {}, UiServices = {}>(options: { name: PluginName; dataFn: (config?: Config) => DataModel; getDefaultDataFn?: (config?: Config) => DataVersioned; outputs: PluginOutputFns; featureFlags?: BlockCodeKnownFeatureFlags; publicOutputDef: PublicOutputDef; }): PluginModelFactory; create(options: { pluginId: Id; transferAt?: V; config?: Config; }): PluginInstance; /** @internal Create a PluginModel from config. Config is captured in getDefaultData closure. */ [CREATE_PLUGIN_MODEL](config?: Config): PluginModel; } /** * Builder for creating PluginType with type-safe output definitions. * * Use `PluginModel.define()` to create a builder instance. * * @typeParam Data - Plugin's persistent data type * @typeParam Params - Params derived from block's RenderCtx (optional) * @typeParam Config - Static configuration passed to plugin factory (optional) * @typeParam Outputs - Accumulated output types * @typeParam Versions - Version map from PluginDataModel (empty for function-based data) * * @example * const dataTable = PluginModel.define({ * name: 'dataTable' as PluginName, * data: pluginDataModel, * }) * .output('model', (ctx) => createTableModel(ctx)) * .build(); */ declare class PluginModelBuilder = {}, ModelServices = {}, UiServices = {}> { protected readonly name: PluginName; protected readonly dataFn: (config?: Config) => DataModel; protected readonly getDefaultDataFn?: (config?: Config) => DataVersioned; private readonly outputs; protected readonly featureFlags?: BlockCodeKnownFeatureFlags; private readonly publicOutputDef; protected constructor(options: { name: PluginName; dataFn: (config?: Config) => DataModel; getDefaultDataFn?: (config?: Config) => DataVersioned; outputs?: PluginOutputFns; featureFlags?: BlockCodeKnownFeatureFlags; publicOutputDef: PublicOutputDef; }); /** @internal */ static [FROM_BUILDER] = {}, ModelServices = {}, UiServices = {}>(options: { name: PluginName; dataFn: (config?: Config) => DataModel; getDefaultDataFn?: (config?: Config) => DataVersioned; outputs?: PluginOutputFns; featureFlags?: BlockCodeKnownFeatureFlags; publicOutputDef: PublicOutputDef; }): PluginModelBuilder; /** * Adds an output to the plugin. * All plugin outputs are always wrapped with status — the UI receives * {@link OutputWithStatus} for every output, allowing it to distinguish * between pending, success, and error states. * * @param key - Output name * @param fn - Function that computes the output value from plugin context * @returns Builder with the new output added * * @example * .output('model', (ctx) => createModel(ctx.params.columns, ctx.data.state)) * .output('pFrame', (ctx) => ctx.createPFrame([...])) */ output(key: Key, fn: (ctx: PluginRenderCtx, ModelServices, UiServices>>) => T): PluginModelBuilder; }, PublicOutputs, Config, Versions, ModelServices, UiServices>; /** * Exposes a plugin data field as a public output — accessible without `usePlugin()` * via `app.plugins.pluginName.publicOutputs.key`. * * The getter runs against the plugin's reactive data object. * Public outputs are read-only. * * @param key - Name of the public output field * @param getter - Function deriving the value from plugin data * * @example * .publicOutput('selection', (d) => d.selection) */ publicOutput(key: Key, getter: (data: Data) => T): PluginModelBuilder; /** * Finalizes the plugin definition and returns a PluginFactory. * * @returns Plugin factory that creates named plugin instances via .create() * * @example * const myPlugin = PluginModel.define({ ... }) * .output('value', (ctx) => ctx.data.value) * .build(); * * // Create a named instance: * const table = myPlugin.create({ pluginId: 'mainTable', config: { ... } }); */ build(): PluginFactory; } /** * Initial builder returned by PluginModel.define(). Extends PluginModelBuilder with .params(). * Once .params() or .output() is called, transitions to PluginModelBuilder (no second .params()). */ declare class PluginModelInitialBuilder = {}, ModelServices = {}, UiServices = {}> extends PluginModelBuilder { /** @internal */ static create = {}, ModelServices = {}, UiServices = {}>(options: { name: PluginName; dataFn: (config?: Config) => DataModel; getDefaultDataFn?: (config?: Config) => DataVersioned; featureFlags?: BlockCodeKnownFeatureFlags; }): PluginModelInitialBuilder; /** * Sets the Params type for this plugin — the shape of data derived from the block's * render context and passed into plugin output functions via `ctx.params`. * Must be called before .output(). Available only on the initial builder. * * @example * .params<{ title: string }>() * .output('displayText', (ctx) => ctx.params.title) */ params

(): PluginModelBuilder; } export {}; //# sourceMappingURL=plugin_model.d.ts.map