@platforma-sdk/ui-vue 1.57.3 → 1.58.0

package/src/internal/createAppV3.ts

@@ -8,12 +8,19 @@ import type {
   ValueWithUTag,
   AuthorMarker,
   PlatformaExtended,
+  InferPluginHandles,
+  PluginHandle,
+  InferFactoryData,
+  InferFactoryOutputs,
+  PluginFactoryLike,
 } from "@platforma-sdk/model";
 import {
   hasAbortError,
   unwrapResult,
   deriveDataFromStorage,
   getPluginData,
+  isPluginOutputKey,
+  pluginOutputPrefix,
 } from "@platforma-sdk/model";
 import type { Ref } from "vue";
 import { reactive, computed, ref } from "vue";
@@ -23,14 +30,16 @@ import { ensureOutputHasStableFlag, MultiError } from "../utils";
 import { applyPatch } from "fast-json-patch";
 import { UpdateSerializer } from "./UpdateSerializer";
 import { watchIgnorable } from "@vueuse/core";
+import type { PluginState, PluginAccess } from "../usePlugin";
 
 export const patchPoolingDelay = 150;
 
-/** Internal interface for plugin data access — injected separately from the app. */
-export interface PluginDataAccess {
-  readonly pluginDataMap: Record<string, unknown>;
-  setPluginData(pluginId: string, value: unknown): Promise<boolean>;
-  initPluginDataSlot(pluginId: string): void;
+/** Internal per-plugin state with reconciliation support. */
+interface InternalPluginState<Data = unknown, Outputs = unknown> extends PluginState<
+  Data,
+  Outputs
+> {
+  readonly ignoreUpdates: (fn: () => void) => void;
 }
 
 export const createNextAuthorMarker = (marker: AuthorMarker | undefined): AuthorMarker => ({
@@ -65,9 +74,10 @@ export function createAppV3<
   Args = unknown,
   Outputs extends BlockOutputsBase = BlockOutputsBase,
   Href extends `/${string}` = `/${string}`,
+  Plugins extends Record<string, unknown> = Record<string, unknown>,
 >(
   state: ValueWithUTag<BlockStateV3<Data, Outputs, Href>>,
-  platforma: PlatformaExtended<PlatformaV3<Data, Args, Outputs, Href>>,
+  platforma: PlatformaExtended<PlatformaV3<Data, Args, Outputs, Href, Plugins>>,
   settings: AppSettings,
 ) {
   const debug = (msg: string, ...rest: unknown[]) => {
@@ -111,19 +121,19 @@ export function createAppV3<
   const debounceSpan = settings.debounceSpan ?? 200;
 
   const setDataQueue = new UpdateSerializer({ debounceSpan });
-  const pluginDataQueues = new Map<string, UpdateSerializer>();
-  const getPluginDataQueue = (pluginId: string): UpdateSerializer => {
-    let queue = pluginDataQueues.get(pluginId);
+  const pluginDataQueues = new Map<PluginHandle, UpdateSerializer>();
+  const getPluginDataQueue = (handle: PluginHandle): UpdateSerializer => {
+    let queue = pluginDataQueues.get(handle);
     if (!queue) {
       queue = new UpdateSerializer({ debounceSpan });
-      pluginDataQueues.set(pluginId, queue);
+      pluginDataQueues.set(handle, queue);
     }
     return queue;
   };
   const setNavigationStateQueue = new UpdateSerializer({ debounceSpan });
 
-  /** Reactive map of plugin data keyed by pluginId. Optimistic state for plugin components. */
-  const pluginDataMap = reactive<Record<string, unknown>>({});
+  /** Lazily-created per-plugin reactive states. */
+  const pluginStates = new Map<PluginHandle, InternalPluginState>();
   /**
    * Reactive snapshot of the application state, including args, outputs, UI state, and navigation state.
    */
@@ -141,25 +151,21 @@ export function createAppV3<
     return platforma.mutateStorage({ operation: "update-block-data", value }, nextAuthorMarker());
   };
 
-  const updatePluginData = async (pluginId: string, value: unknown) => {
+  const updatePluginData = async (handle: PluginHandle, value: unknown) => {
     return platforma.mutateStorage(
-      { operation: "update-plugin-data", pluginId, value },
+      { operation: "update-plugin-data", pluginId: handle, value },
       nextAuthorMarker(),
     );
   };
 
-  /** Derives plugin data for a given pluginId from the current snapshot. */
-  const derivePluginDataFromSnapshot = (pluginId: string): unknown => {
-    return getPluginData(snapshot.value.blockStorage, pluginId);
-  };
-
   const setNavigationState = async (state: NavigationState<Href>) => {
     return platforma.setNavigationState(state);
   };
 
   const outputs = computed<OutputValues<Outputs>>(() => {
-    const entries = Object.entries(snapshot.value.outputs as Partial<Readonly<Outputs>>).map(
-      ([k, outputWithStatus]) =>
+    const entries = Object.entries(snapshot.value.outputs as Partial<Readonly<Outputs>>)
+      .filter(([k]) => !isPluginOutputKey(k))
+      .map(([k, outputWithStatus]) =>
         platforma.blockModelInfo.outputs[k]?.withStatus
           ? [k, ensureOutputHasStableFlag(outputWithStatus)]
           : [
@@ -168,17 +174,17 @@ export function createAppV3<
                 ? outputWithStatus.value
                 : undefined,
             ],
-    );
+      );
     return Object.fromEntries(entries);
   });
 
   const outputErrors = computed<OutputErrors<Outputs>>(() => {
-    const entries = Object.entries(snapshot.value.outputs as Partial<Readonly<Outputs>>).map(
-      ([k, vOrErr]) => [
+    const entries = Object.entries(snapshot.value.outputs as Partial<Readonly<Outputs>>)
+      .filter(([k]) => !isPluginOutputKey(k))
+      .map(([k, vOrErr]) => [
         k,
         vOrErr && vOrErr.ok === false ? new MultiError(vOrErr.errors) : undefined,
-      ],
-    );
+      ]);
     return Object.fromEntries(entries);
   });
 
@@ -251,8 +257,12 @@ export function createAppV3<
             snapshot.value = applyPatch(snapshot.value, patches.value, false, false).newDocument;
             updateAppModel({ data: deriveDataFromStorage<Data>(snapshot.value.blockStorage) });
             // Reconcile plugin data from external source
-            for (const pluginId of Object.keys(pluginDataMap)) {
-              pluginDataMap[pluginId] = derivePluginDataFromSnapshot(pluginId);
+            for (const [handle, pluginState] of pluginStates) {
+              pluginState.ignoreUpdates(() => {
+                pluginState.model.data = deepClone(
+                  getPluginData(snapshot.value.blockStorage, handle),
+                );
+              });
             }
             data.isExternalSnapshot = isAuthorChanged;
           });
@@ -318,26 +328,83 @@ export function createAppV3<
     },
   };
 
+  /** Creates a lazily-cached per-plugin reactive state. */
+  const createPluginState = <F extends PluginFactoryLike>(
+    handle: PluginHandle<F>,
+  ): InternalPluginState<InferFactoryData<F>, InferFactoryOutputs<F>> => {
+    const prefix = pluginOutputPrefix(handle);
+
+    const pluginOutputs = computed(() => {
+      const result: Record<string, unknown> = {};
+      for (const [key, outputWithStatus] of Object.entries(
+        snapshot.value.outputs as Partial<Readonly<Outputs>>,
+      )) {
+        if (!key.startsWith(prefix)) continue;
+        result[key.slice(prefix.length)] =
+          outputWithStatus.ok && outputWithStatus.value !== undefined
+            ? outputWithStatus.value
+            : undefined;
+      }
+      return result;
+    });
+
+    const pluginOutputErrors = computed(() => {
+      const result: Record<string, Error | undefined> = {};
+      for (const [key, vOrErr] of Object.entries(
+        snapshot.value.outputs as Partial<Readonly<Outputs>>,
+      )) {
+        if (!key.startsWith(prefix)) continue;
+        result[key.slice(prefix.length)] =
+          vOrErr && vOrErr.ok === false ? new MultiError(vOrErr.errors) : undefined;
+      }
+      return result;
+    });
+
+    const pluginModel = reactive({
+      data: deepClone(getPluginData(snapshot.value.blockStorage, handle)),
+      outputs: pluginOutputs,
+      outputErrors: pluginOutputErrors,
+    }) as InternalPluginState<InferFactoryData<F>, InferFactoryOutputs<F>>["model"];
+
+    const { ignoreUpdates } = watchIgnorable(
+      () => pluginModel.data,
+      (newData) => {
+        if (newData === undefined) return;
+        debug("plugin setData", handle, newData);
+        getPluginDataQueue(handle).run(() =>
+          updatePluginData(handle, deepClone(newData)).then(unwrapResult),
+        );
+      },
+      { deep: true },
+    );
+
+    return {
+      model: pluginModel,
+      ignoreUpdates,
+    };
+  };
+
   /** Plugin internals — provided via separate injection key, not exposed on useApp(). */
-  const pluginAccess: PluginDataAccess = {
-    pluginDataMap,
-    setPluginData(pluginId: string, value: unknown): Promise<boolean> {
-      pluginDataMap[pluginId] = value;
-      debug("setPluginData", pluginId, value);
-      return getPluginDataQueue(pluginId).run(() =>
-        updatePluginData(pluginId, value).then(unwrapResult),
-      );
-    },
-    initPluginDataSlot(pluginId: string): void {
-      if (!(pluginId in pluginDataMap)) {
-        pluginDataMap[pluginId] = derivePluginDataFromSnapshot(pluginId);
+  const pluginAccess: PluginAccess = {
+    getOrCreatePluginState<F extends PluginFactoryLike>(handle: PluginHandle<F>) {
+      const existing = pluginStates.get(handle);
+      if (existing) {
+        return existing as unknown as PluginState<InferFactoryData<F>, InferFactoryOutputs<F>>;
       }
+      const state = createPluginState(handle);
+      pluginStates.set(handle, state);
+      return state;
     },
   };
 
+  const plugins = Object.fromEntries(
+    platforma.blockModelInfo.pluginIds.map((id) => [id, id]),
+  ) as InferPluginHandles<Plugins>;
+
   const getters = {
     closedRef,
     snapshot,
+    plugins,
     queryParams: computed(() => parseQuery<Href>(snapshot.value.navigationState.href as Href)),
     href: computed(() => snapshot.value.navigationState.href),
     hasErrors: computed(() =>
@@ -360,4 +427,5 @@ export type BaseAppV3<
   Args = unknown,
   Outputs extends BlockOutputsBase = BlockOutputsBase,
   Href extends `/${string}` = `/${string}`,
-> = ReturnType<typeof createAppV3<Data, Args, Outputs, Href>>["app"];
+  Plugins extends Record<string, unknown> = Record<string, unknown>,
+> = ReturnType<typeof createAppV3<Data, Args, Outputs, Href, Plugins>>["app"];

package/src/lib.ts

@@ -35,7 +35,15 @@ export * from "./components/PlAdvancedFilter";
 
 export * from "./defineApp";
 
-export { usePluginData } from "./usePluginData";
+export { usePlugin } from "./usePlugin";
+export type { PluginState } from "./usePlugin";
+export type {
+  PluginHandle,
+  PluginFactoryLike,
+  InferPluginHandle,
+  InferFactoryData,
+  InferFactoryOutputs,
+} from "@platforma-sdk/model";
 
 export * from "./createModel";
 

package/src/usePlugin.ts

@@ -0,0 +1,65 @@
+import { inject, type Reactive } from "vue";
+import { pluginDataKey } from "./defineApp";
+import type {
+  PluginHandle,
+  InferFactoryData,
+  InferFactoryOutputs,
+  PluginFactoryLike,
+} from "@platforma-sdk/model";
+
+/** Per-plugin reactive model exposed to consumers via usePlugin(). */
+export interface PluginState<Data = unknown, Outputs = unknown> {
+  readonly model: Reactive<{
+    data: Data;
+    outputs: Outputs extends Record<string, unknown>
+      ? { [K in keyof Outputs]: Outputs[K] | undefined }
+      : Record<string, unknown>;
+    outputErrors: Outputs extends Record<string, unknown>
+      ? { [K in keyof Outputs]?: Error }
+      : Record<string, Error | undefined>;
+  }>;
+}
+
+/** Internal interface for plugin access — provided via Vue injection to usePlugin(). */
+export interface PluginAccess {
+  getOrCreatePluginState<F extends PluginFactoryLike>(
+    handle: PluginHandle<F>,
+  ): PluginState<InferFactoryData<F>, InferFactoryOutputs<F>>;
+}
+
+/**
+ * Composable for accessing a plugin's reactive model: data, outputs, and outputErrors.
+ *
+ * Mirrors the `app.model` access pattern — `plugin.model.data` is reactive and deep-watched,
+ * mutations are automatically queued and sent to storage.
+ *
+ * @param handle - Opaque plugin handle obtained from `app.plugins`.
+ * @typeParam F - The plugin factory type (inferred from the handle)
+ *
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { usePlugin, type InferPluginHandle } from '@platforma-sdk/ui-vue';
+ * import type { CounterPlugin } from './plugins/counter';
+ *
+ * const props = defineProps<{ instance: InferPluginHandle<CounterPlugin> }>();
+ * const plugin = usePlugin(props.instance);
+ *
+ * plugin.model.data.count += 1;          // reactive, triggers storage update
+ * plugin.model.outputs.displayText       // computed, plugin's own outputs only
+ * plugin.model.outputErrors.displayText  // Error | undefined
+ * </script>
+ * ```
+ */
+export function usePlugin<F extends PluginFactoryLike>(handle: PluginHandle<F>) {
+  const access = inject<PluginAccess>(pluginDataKey);
+
+  if (!access) {
+    throw new Error(
+      "usePlugin requires a V3 block (BlockModelV3). " +
+        "Make sure the block uses apiVersion 3 and the plugin is installed.",
+    );
+  }
+
+  return access.getOrCreatePluginState<F>(handle);
+}

package/dist/usePluginData.d.ts

@@ -1,30 +0,0 @@
-/**
- * Composable for accessing and updating plugin-specific data.
- *
- * Plugin components are self-contained: they use this composable to read/write
- * their own data slice from BlockStorage without knowing about the parent block's data.
- *
- * Requires a V3 block (BlockModelV3). Throws if used in a V1/V2 block.
- *
- * @param pluginId - The plugin instance ID (must match the ID used in BlockModelV3.plugin()).
- *   Must be a static value; changing it after mount will not re-bind the composable.
- * @returns `{ data, updateData }` where `data` is a reactive ref to the plugin's data,
- *   and `updateData` returns a promise resolving to `true` if the mutation was sent,
- *   or `false` if data is not yet available.
- *
- * @example
- * ```vue
- * <script setup lang="ts">
- * const { data, updateData } = usePluginData<CounterData>('counter');
- *
- * function increment() {
- *   updateData((d) => ({ ...d, count: d.count + 1 }));
- * }
- * </script>
- * ```
- */
-export declare function usePluginData<Data>(pluginId: string): {
-    data: import('vue').ComputedRef<Data | undefined>;
-    updateData: (cb: (current: Data) => Data) => Promise<boolean>;
-};
-//# sourceMappingURL=usePluginData.d.ts.map

package/dist/usePluginData.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"usePluginData.d.ts","sourceRoot":"","sources":["../src/usePluginData.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM;;qBAwB1B,CAAC,OAAO,EAAE,IAAI,KAAK,IAAI,KAAG,OAAO,CAAC,OAAO,CAAC;EAQnE"}

package/dist/usePluginData.js

@@ -1,22 +0,0 @@
-import { inject as i, computed as u } from "vue";
-import { deepClone as s } from "./lib/util/helpers/dist/objects.js";
-import { pluginDataKey as l } from "./defineApp.js";
-function d(t) {
-  const e = i(l);
-  if (!e)
-    throw new Error(
-      "usePluginData requires a V3 block (BlockModelV3). Make sure the block uses apiVersion 3 and the plugin is installed."
-    );
-  e.initPluginDataSlot(t);
-  const a = u(() => e.pluginDataMap[t]);
-  return { data: a, updateData: (o) => {
-    const r = a.value;
-    if (r === void 0) return Promise.resolve(!1);
-    const n = o(s(r));
-    return e.setPluginData(t, n);
-  } };
-}
-export {
-  d as usePluginData
-};
-//# sourceMappingURL=usePluginData.js.map

package/dist/usePluginData.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"usePluginData.js","sources":["../src/usePluginData.ts"],"sourcesContent":["import { computed, inject } from \"vue\";\nimport { deepClone } from \"@milaboratories/helpers\";\nimport { pluginDataKey } from \"./defineApp\";\nimport type { PluginDataAccess } from \"./internal/createAppV3\";\n\n/**\n * Composable for accessing and updating plugin-specific data.\n *\n * Plugin components are self-contained: they use this composable to read/write\n * their own data slice from BlockStorage without knowing about the parent block's data.\n *\n * Requires a V3 block (BlockModelV3). Throws if used in a V1/V2 block.\n *\n * @param pluginId - The plugin instance ID (must match the ID used in BlockModelV3.plugin()).\n *   Must be a static value; changing it after mount will not re-bind the composable.\n * @returns `{ data, updateData }` where `data` is a reactive ref to the plugin's data,\n *   and `updateData` returns a promise resolving to `true` if the mutation was sent,\n *   or `false` if data is not yet available.\n *\n * @example\n * ```vue\n * <script setup lang=\"ts\">\n * const { data, updateData } = usePluginData<CounterData>('counter');\n *\n * function increment() {\n *   updateData((d) => ({ ...d, count: d.count + 1 }));\n * }\n * </script>\n * ```\n */\nexport function usePluginData<Data>(pluginId: string) {\n  const access = inject<PluginDataAccess>(pluginDataKey);\n\n  if (!access) {\n    throw new Error(\n      \"usePluginData requires a V3 block (BlockModelV3). \" +\n        \"Make sure the block uses apiVersion 3 and the plugin is installed.\",\n    );\n  }\n\n  // Initialize the plugin data slot from snapshot if not already done\n  access.initPluginDataSlot(pluginId);\n\n  // Reactive reference to the plugin's data in the shared optimistic map\n  const data = computed<Data | undefined>(() => {\n    return access.pluginDataMap[pluginId] as Data | undefined;\n  });\n\n  /**\n   * Update plugin data with optimistic feedback.\n   *\n   * @param cb - Callback that receives a deep clone of current data and returns new data.\n   * @returns Promise that resolves to true when the mutation is sent\n   */\n  const updateData = (cb: (current: Data) => Data): Promise<boolean> => {\n    const current = data.value;\n    if (current === undefined) return Promise.resolve(false);\n    const newValue = cb(deepClone(current));\n    return access.setPluginData(pluginId, newValue);\n  };\n\n  return { data, updateData };\n}\n"],"names":["usePluginData","pluginId","access","inject","pluginDataKey","data","computed","cb","current","newValue","deepClone"],"mappings":";;;AA8BO,SAASA,EAAoBC,GAAkB;AACpD,QAAMC,IAASC,EAAyBC,CAAa;AAErD,MAAI,CAACF;AACH,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAMJ,EAAAA,EAAO,mBAAmBD,CAAQ;AAGlC,QAAMI,IAAOC,EAA2B,MAC/BJ,EAAO,cAAcD,CAAQ,CACrC;AAeD,SAAO,EAAE,MAAAI,GAAM,YAPI,CAACE,MAAkD;AACpE,UAAMC,IAAUH,EAAK;AACrB,QAAIG,MAAY,OAAW,QAAO,QAAQ,QAAQ,EAAK;AACvD,UAAMC,IAAWF,EAAGG,EAAUF,CAAO,CAAC;AACtC,WAAON,EAAO,cAAcD,GAAUQ,CAAQ;AAAA,EAChD,EAEe;AACjB;"}

package/src/usePluginData.ts

@@ -1,63 +0,0 @@
-import { computed, inject } from "vue";
-import { deepClone } from "@milaboratories/helpers";
-import { pluginDataKey } from "./defineApp";
-import type { PluginDataAccess } from "./internal/createAppV3";
-
-/**
- * Composable for accessing and updating plugin-specific data.
- *
- * Plugin components are self-contained: they use this composable to read/write
- * their own data slice from BlockStorage without knowing about the parent block's data.
- *
- * Requires a V3 block (BlockModelV3). Throws if used in a V1/V2 block.
- *
- * @param pluginId - The plugin instance ID (must match the ID used in BlockModelV3.plugin()).
- *   Must be a static value; changing it after mount will not re-bind the composable.
- * @returns `{ data, updateData }` where `data` is a reactive ref to the plugin's data,
- *   and `updateData` returns a promise resolving to `true` if the mutation was sent,
- *   or `false` if data is not yet available.
- *
- * @example
- * ```vue
- * <script setup lang="ts">
- * const { data, updateData } = usePluginData<CounterData>('counter');
- *
- * function increment() {
- *   updateData((d) => ({ ...d, count: d.count + 1 }));
- * }
- * </script>
- * ```
- */
-export function usePluginData<Data>(pluginId: string) {
-  const access = inject<PluginDataAccess>(pluginDataKey);
-
-  if (!access) {
-    throw new Error(
-      "usePluginData requires a V3 block (BlockModelV3). " +
-        "Make sure the block uses apiVersion 3 and the plugin is installed.",
-    );
-  }
-
-  // Initialize the plugin data slot from snapshot if not already done
-  access.initPluginDataSlot(pluginId);
-
-  // Reactive reference to the plugin's data in the shared optimistic map
-  const data = computed<Data | undefined>(() => {
-    return access.pluginDataMap[pluginId] as Data | undefined;
-  });
-
-  /**
-   * Update plugin data with optimistic feedback.
-   *
-   * @param cb - Callback that receives a deep clone of current data and returns new data.
-   * @returns Promise that resolves to true when the mutation is sent
-   */
-  const updateData = (cb: (current: Data) => Data): Promise<boolean> => {
-    const current = data.value;
-    if (current === undefined) return Promise.resolve(false);
-    const newValue = cb(deepClone(current));
-    return access.setPluginData(pluginId, newValue);
-  };
-
-  return { data, updateData };
-}