@ethisyscore/plugin-ui 1.123.0 → 1.125.0

package/README.md

@@ -16,7 +16,7 @@ and the shared MUI component surface externalised to the host's instances.
 | Subpath | Key exports | Purpose |
 |---|---|---|
 | `.` | `createPortBridgeClient`, `BridgeClientContext` / `useBridgeClient`, `useBridgeTheme` / `useBridgeLocale`, `ExtensionRuntimeProvider`, `useMcpResource` / `useMcpTool` / `useMcpQuery` / `unwrapItems`, `useHostIdentity` / `useCurrentUser`, `definePlatformReactPage` / `emitNavigation` / `PlatformReactPageProps` | Bridge client + theme/locale context, brokered-MCP data hooks, host identity, and the base PlatformReact page contract |
-| `./platform-react` | `definePlatformReactPluginPage` / `createPluginPageDefiner`, `definePlatformReactPluginOverlay` / `useOverlayHost`, `useView` / `createUseView` / `ViewComponent` / `isComponent`, `BaseMcpService` / `useToolInvoker` / `useToolInvokerMap`, `useAuthenticatedQuery` / `useAuthenticatedQueries`, `injectPluginStyles` / `PluginStyleScope`, `createReactRouterShim`, `usePluginRealtime`, `useMcpUpload`, `useManagedLifecycle` | The plugin authoring layer: page/overlay wrappers (react-query + manifest + style root), the static `useView` adapter pattern, the MCP service base + tool invokers, pre-authenticated react-query wrappers, scoped-style injection, router shim, realtime, and file upload |
+| `./platform-react` | `definePlatformReactPluginPage` / `createPluginPageDefiner`, `definePlatformReactPluginOverlay` / `useOverlayHost`, `useView` / `createUseView` / `ViewComponent` / `isComponent`, `BaseMcpService` / `useToolInvoker` / `useToolInvokerMap`, `useAuthenticatedQuery` / `useAuthenticatedQueries`, `injectPluginStyles` / `PluginStyleScope`, `createReactRouterShim`, `usePluginRealtime`, `useBackgroundOperation` / `useOperationsByParent` / `useLatestTerminalOperationByParent` / `hasKind`, `useMcpUpload`, `useManagedLifecycle` | The plugin authoring layer: page/overlay wrappers (react-query + manifest + style root), the static `useView` adapter pattern, the MCP service base + tool invokers, pre-authenticated react-query wrappers, scoped-style injection, router shim, realtime, following the plugin's own background operations, and file upload |
 | `./icons` | `NextureIcons`, `IconMap`, 470+ `Ni*` icon components, `sizeHelper` / `strokeSizeHelper`, `IconName` / `IconSize` / `IconVariant` | The gogo-ui "nexture" SVG icon set with props types and size/stroke helpers |
 | `./components/ui` | `Button`, `Card`, `Dialog`, `Table`, `TextField`, `Select`, `Tabs`, `Typography`, `Grid`, `Stack`, `Menu`, `DebouncedSearchInput`, … | MUI component re-exports plus the Dialog scroll-lock wrapper and the debounced search field. These are **host externals** — never bundled; production builds bind them to the host's MUI instance |
 | `./components/layout` | `PageHeader` / `usePageHeader` / `withPageHeader` / `buildBreadcrumbs`, `FillGrid` / `FillGridItem` / `FillGap` / `FillSpan`, sidebar-action context (`SidebarActionProvider`, `useSidebarAction` / `useSidebarActions` / `useTriggerSidebarAction`), `RouteMeta` / `RouteMetaEntry` | Layout primitives (flex-wrap grid), the page-header layer + breadcrumb builder, and the sidebar-action context/provider |

package/dist/platform-react/index.cjs

@@ -766,6 +766,147 @@ function usePluginRealtime(typeCode, handler) {
     return source.subscribe(typeCode, (payload) => ref.current(payload));
   }, [source, typeCode]);
 }
+
+// src/platform-react/operations/asStateChanged.ts
+function asStateChanged(payload) {
+  if (payload == null || typeof payload !== "object") {
+    return null;
+  }
+  const candidate = payload;
+  return typeof candidate.operationId === "string" && typeof candidate.eventSequence === "number" ? candidate : null;
+}
+
+// src/platform-react/operations/mergeOperation.ts
+function mergeOperation(current, event) {
+  if (current && current.eventSequence >= event.eventSequence) {
+    return current;
+  }
+  const { extensionId: _extensionId, previousStatus: _previousStatus, ...fields } = event;
+  return { ...fields, resultPayloadJson: current?.resultPayloadJson ?? null };
+}
+function mergeIntoList(current, event) {
+  const rows = current ?? [];
+  const index = rows.findIndex((r) => r.operationId === event.operationId);
+  if (index < 0) {
+    return [mergeOperation(null, event), ...rows];
+  }
+  const merged = mergeOperation(rows[index], event);
+  if (merged === rows[index]) {
+    return rows;
+  }
+  const next = rows.slice();
+  next[index] = merged;
+  return next;
+}
+
+// src/platform-react/operations/queryKeys.ts
+var pluginOperationKeys = {
+  all: ["plugin-operations"],
+  byId: (operationId) => ["plugin-operations", "get", operationId],
+  byParent: (parentEntityType, parentEntityId) => ["plugin-operations", "by-parent", parentEntityType, parentEntityId],
+  latestTerminalByParent: (parentEntityType, parentEntityId) => ["plugin-operations", "latest-terminal", parentEntityType, parentEntityId]
+};
+
+// src/platform-react/operations/status.ts
+var TERMINAL = /* @__PURE__ */ new Set(["Succeeded", "Failed", "Cancelled"]);
+function isTerminalOperationStatus(status) {
+  return status != null && TERMINAL.has(status);
+}
+
+// src/platform-react/operations/types.ts
+var PLUGIN_OPERATION_STATE_CHANGED = "operations.plugin-operation.state-changed";
+var PLUGIN_OPERATION_TOOLS = {
+  get: "plugin-operations:get",
+  listByParent: "plugin-operations:list-by-parent",
+  listActive: "plugin-operations:list-active",
+  latestTerminalByParent: "plugin-operations:latest-terminal-by-parent"
+};
+var OPERATION_FALLBACK_POLL_MS = 8e3;
+
+// src/platform-react/operations/useBackgroundOperation.ts
+function useBackgroundOperation(operationId) {
+  const queryClient = reactQuery.useQueryClient();
+  const realtime = extensionRuntime.usePluginRealtimeSource();
+  const { invoke } = extensionRuntime.useMcpTool(PLUGIN_OPERATION_TOOLS.get);
+  const query = reactQuery.useQuery({
+    queryKey: pluginOperationKeys.byId(operationId ?? ""),
+    enabled: Boolean(operationId),
+    // Never undefined: TanStack Query rejects an undefined result.
+    queryFn: async () => await invoke({ operationId }) ?? null,
+    refetchInterval: (q) => realtime === null && q.state.data != null && !isTerminalOperationStatus(q.state.data.status) ? OPERATION_FALLBACK_POLL_MS : false
+  });
+  usePluginRealtime(PLUGIN_OPERATION_STATE_CHANGED, (payload) => {
+    const event = asStateChanged(payload);
+    if (!operationId || event?.operationId !== operationId) {
+      return;
+    }
+    const key = pluginOperationKeys.byId(operationId);
+    const before = queryClient.getQueryData(key);
+    const merged = mergeOperation(before, event);
+    queryClient.setQueryData(key, merged);
+    if (merged !== before && isTerminalOperationStatus(merged.status)) {
+      void queryClient.invalidateQueries({ queryKey: key });
+    }
+  });
+  return query;
+}
+
+// src/platform-react/operations/hasKind.ts
+var KIND_SCOPE = /^p:[0-9a-f]{32}:/i;
+var PARENT_SCOPE = /^po:[0-9A-F]{32}:/i;
+function hasKind(operation, unscopedKind) {
+  const kind = typeof operation === "string" ? operation : operation?.kind;
+  return kind != null && kind.replace(KIND_SCOPE, "") === unscopedKind;
+}
+function hasParentEntityType(operation, unscopedParentEntityType) {
+  const parentType = typeof operation === "string" ? operation : operation?.parentEntityType;
+  return parentType != null && parentType.replace(PARENT_SCOPE, "") === unscopedParentEntityType;
+}
+
+// src/platform-react/operations/useOperationsByParent.ts
+function useOperationsByParent(parentEntityType, parentEntityId) {
+  const queryClient = reactQuery.useQueryClient();
+  const realtime = extensionRuntime.usePluginRealtimeSource();
+  const { invoke } = extensionRuntime.useMcpTool(
+    PLUGIN_OPERATION_TOOLS.listByParent
+  );
+  const query = reactQuery.useQuery({
+    queryKey: pluginOperationKeys.byParent(parentEntityType, parentEntityId ?? ""),
+    enabled: Boolean(parentEntityId),
+    queryFn: async () => (await invoke({ parentEntityType, parentEntityId }))?.items ?? [],
+    refetchInterval: (q) => realtime === null && (q.state.data ?? []).some((op) => !isTerminalOperationStatus(op.status)) ? OPERATION_FALLBACK_POLL_MS : false
+  });
+  usePluginRealtime(PLUGIN_OPERATION_STATE_CHANGED, (payload) => {
+    const event = asStateChanged(payload);
+    if (!parentEntityId || event == null || event.parentEntityId !== parentEntityId || !hasParentEntityType(event, parentEntityType)) {
+      return;
+    }
+    queryClient.setQueryData(
+      pluginOperationKeys.byParent(parentEntityType, parentEntityId),
+      (current) => mergeIntoList(current, event)
+    );
+  });
+  return query;
+}
+function useLatestTerminalOperationByParent(parentEntityType, parentEntityId) {
+  const queryClient = reactQuery.useQueryClient();
+  const { invoke } = extensionRuntime.useMcpTool(
+    PLUGIN_OPERATION_TOOLS.latestTerminalByParent
+  );
+  const key = pluginOperationKeys.latestTerminalByParent(parentEntityType, parentEntityId ?? "");
+  const query = reactQuery.useQuery({
+    queryKey: key,
+    enabled: Boolean(parentEntityId),
+    queryFn: async () => (await invoke({ parentEntityType, parentEntityId }))?.item ?? null
+  });
+  usePluginRealtime(PLUGIN_OPERATION_STATE_CHANGED, (payload) => {
+    const event = asStateChanged(payload);
+    if (parentEntityId && event != null && event.parentEntityId === parentEntityId && hasParentEntityType(event, parentEntityType) && isTerminalOperationStatus(event.status)) {
+      void queryClient.invalidateQueries({ queryKey: key });
+    }
+  });
+  return query;
+}
 var DEFAULT_MAX_UPLOAD_BYTES = 30 * 1024 * 1024;
 function useMcpUpload(opts) {
   const transport = extensionRuntime.useExtensionRuntimeTransport(opts?.transport);
@@ -1282,9 +1423,12 @@ exports.HOST_CHROME_CONTRACT_VERSION = HOST_CHROME_CONTRACT_VERSION;
 exports.HostSidebarActionsContext = HostSidebarActionsContext;
 exports.LIST_CURRENCIES_TOOL = LIST_CURRENCIES_TOOL;
 exports.MissingViewFallback = MissingViewFallback;
+exports.OPERATION_FALLBACK_POLL_MS = OPERATION_FALLBACK_POLL_MS;
 exports.ORGANISATION_SETTINGS_URI = ORGANISATION_SETTINGS_URI;
 exports.OVERLAY_HOST_CONTRACT_VERSION = OVERLAY_HOST_CONTRACT_VERSION;
 exports.OverlayHostContext = OverlayHostContext;
+exports.PLUGIN_OPERATION_STATE_CHANGED = PLUGIN_OPERATION_STATE_CHANGED;
+exports.PLUGIN_OPERATION_TOOLS = PLUGIN_OPERATION_TOOLS;
 exports.PluginPortalScope = PluginPortalScope;
 exports.PluginStyleScope = PluginStyleScope;
 exports.REPORTING_CURRENCY_TOOL = REPORTING_CURRENCY_TOOL2;
@@ -1301,13 +1445,17 @@ exports.createUseView = createUseView;
 exports.definePlatformReactPluginOverlay = definePlatformReactPluginOverlay;
 exports.definePlatformReactPluginPage = definePlatformReactPluginPage;
 exports.deriveHostEntityToken = deriveHostEntityToken;
+exports.hasKind = hasKind;
+exports.hasParentEntityType = hasParentEntityType;
 exports.injectPluginStyles = injectPluginStyles;
 exports.isComponent = isComponent;
 exports.isHostChromeCompatible = isHostChromeCompatible;
+exports.isTerminalOperationStatus = isTerminalOperationStatus;
 exports.mcpTool = mcpTool;
 exports.menuConfigToHostSidebarInput = menuConfigToHostSidebarInput;
 exports.normaliseSlug = normaliseSlug;
 exports.notViaMcp = notViaMcp;
+exports.pluginOperationKeys = pluginOperationKeys;
 exports.reportHostChromeDiagnostic = reportHostChromeDiagnostic;
 exports.resolveActiveNavHref = resolveActiveNavHref;
 exports.resolveSurfaceBase = resolveSurfaceBase;
@@ -1316,10 +1464,13 @@ exports.surfacePathFor = surfacePathFor;
 exports.toHostSidebarInput = toHostSidebarInput;
 exports.useAuthenticatedQueries = useAuthenticatedQueries;
 exports.useAuthenticatedQuery = useAuthenticatedQuery;
+exports.useBackgroundOperation = useBackgroundOperation;
 exports.useCurrency = useCurrency;
 exports.useHostSidebarActions = useHostSidebarActions;
+exports.useLatestTerminalOperationByParent = useLatestTerminalOperationByParent;
 exports.useManagedLifecycle = useManagedLifecycle;
 exports.useMcpUpload = useMcpUpload;
+exports.useOperationsByParent = useOperationsByParent;
 exports.useOrgFormatSync = useOrgFormatSync;
 exports.useOverlayHost = useOverlayHost;
 exports.usePluginRealtime = usePluginRealtime;