@vc-shell/framework 1.2.1 → 1.2.3-beta.0

package/core/plugins/ai-agent/types.ts

@@ -0,0 +1,310 @@
+import { ComputedRef, Ref } from "vue";
+
+// ============================================
+// Core Types
+// ============================================
+
+/**
+ * Context type for AI agent - determines UI behavior in chatbot
+ * - 'list': Multiple selected items from a list blade (shows "X items selected" badge)
+ * - 'details': Single item being edited in details blade (shows suggestions UI)
+ */
+export type AiAgentContextType = "list" | "details";
+
+/**
+ * Suggestion card for AI agent
+ */
+export interface ISuggestion {
+  /** Unique identifier */
+  id: string;
+  /** Display title */
+  title: string;
+  /** Icon name */
+  icon: string;
+  /** Icon color (optional) */
+  iconColor?: string;
+  /** Prompt text to send when clicked */
+  prompt: string;
+}
+
+/**
+ * Options for useAiAgentContext composable
+ */
+export interface UseAiAgentContextOptions<T = Record<string, unknown>> {
+  /**
+   * Ref with data - accepts both formats:
+   * - Ref<T> for DETAILS blade (single object, will be wrapped in array internally)
+   * - Ref<T[]> for LIST blade (array of selected objects)
+   *
+   * When AI agent sends changes back, they will be applied to:
+   * - The object directly (for single-object refs)
+   * - The first item in array (for array refs)
+   */
+  dataRef: Ref<T> | Ref<T[]>;
+
+  /** Custom suggestions for this blade */
+  suggestions?: ISuggestion[];
+}
+
+/**
+ * Return type for useAiAgentContext composable
+ */
+export interface UseAiAgentContextReturn {
+  /** Preview state (for details blades) */
+  previewState: {
+    isActive: ComputedRef<boolean>;
+    changedFields: ComputedRef<string[]>;
+  };
+}
+
+// ============================================
+// AI Agent Panel Types
+// ============================================
+
+/**
+ * State of the AI agent panel
+ */
+export type AiAgentPanelState = "closed" | "open" | "expanded";
+
+/**
+ * Configuration for the AI agent panel
+ */
+export interface IAiAgentConfig {
+  /** URL of the AI agent iframe */
+  url: string;
+  /** Panel title (default: "Virto OZ") */
+  title?: string;
+  /** Panel width in pixels when open (default: 350) */
+  width?: number;
+  /** Panel width in pixels when expanded (default: 500) */
+  expandedWidth?: number;
+  /** Allowed origins for postMessage (default: ["*"]) */
+  allowedOrigins?: string[];
+  /**
+   * Tenant identifier for the platform instance.
+   * This should be a static value identifying the platform installation (e.g., "virto", "acme-corp").
+   * Configured by the host application via VirtoShellFramework options.
+   *
+   */
+  tenantId?: string;
+}
+
+/**
+ * Current blade information for AI context
+ */
+export interface IAiAgentBladeContext {
+  /** Blade identifier */
+  id: string;
+  /** Blade component name */
+  name: string;
+  /** Blade display title */
+  title?: string;
+  /** Route parameter (e.g., item ID being edited) */
+  param?: string;
+  /** Additional blade options */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * User information for AI context
+ */
+export interface IAiAgentUserContext {
+  id?: string;
+  userName?: string;
+  isAdministrator?: boolean;
+  permissions?: string[];
+}
+
+/**
+ * Full context passed to the AI agent
+ */
+export interface IAiAgentContext {
+  /** Current user information */
+  user: IAiAgentUserContext | undefined;
+  /** Current active blade information */
+  currentBlade: IAiAgentBladeContext | null;
+  /** Data items (from useAiAgentContext) */
+  items: Record<string, unknown>[];
+  /** Timestamp of context generation */
+  timestamp: number;
+}
+
+/**
+ * Service for managing AI agent state and communication
+ */
+export interface IAiAgentService {
+  /** Current panel state */
+  panelState: Ref<AiAgentPanelState>;
+  /** Panel configuration */
+  config: Ref<IAiAgentConfig>;
+  /** Current context (reactive) */
+  context: ComputedRef<IAiAgentContext>;
+  /** Whether panel is open (not closed) */
+  isOpen: ComputedRef<boolean>;
+  /** Whether panel is in expanded state */
+  isExpanded: ComputedRef<boolean>;
+  /** Total count of items in current context */
+  totalItemsCount: ComputedRef<number>;
+
+  /** Open the AI panel */
+  openPanel: () => void;
+  /** Close the AI panel */
+  closePanel: () => void;
+  /** Toggle panel open/close */
+  togglePanel: () => void;
+  /** Expand the panel to larger width */
+  expandPanel: () => void;
+  /** Collapse panel to normal width */
+  collapsePanel: () => void;
+
+  /** Update configuration */
+  setConfig: (config: Partial<IAiAgentConfig>) => void;
+
+  /** Send message to AI agent iframe */
+  sendMessage: (type: AiAgentMessageType, payload: unknown) => void;
+  /** Register message handler, returns unsubscribe function */
+  onMessage: (handler: (event: IAiAgentMessage) => void) => () => void;
+}
+
+// ============================================
+// PostMessage Protocol Types
+// ============================================
+
+/**
+ * Message types sent from Shell to Chatbot
+ */
+export type ShellToChatMessageType =
+  | "INIT_CONTEXT" // Initial context when chatbot loads
+  | "UPDATE_CONTEXT"; // Context updates (items, blade changes)
+
+/**
+ * Message types sent from Chatbot to Shell
+ */
+export type ChatToShellMessageType =
+  | "CHAT_READY" // Chatbot is loaded and ready
+  | "NAVIGATE_TO_APP" // Request to navigate to a blade
+  | "EXPAND_IN_CHAT" // Request to expand item in chat
+  | "RELOAD_BLADE" // Request to reload current blade
+  | "PREVIEW_CHANGES" // Request to preview changes in form
+  | "APPLY_CHANGES" // Request to apply data changes
+  | "DOWNLOAD_FILE" // Request to download file
+  | "SHOW_MORE" // Request for more results
+  | "CHAT_ERROR"; // Error notification
+
+/**
+ * Combined message types
+ */
+export type AiAgentMessageType = ShellToChatMessageType | ChatToShellMessageType;
+
+/**
+ * Generic message type (for handlers)
+ */
+export interface IAiAgentMessage<T = unknown> {
+  /** Message type identifier */
+  type: AiAgentMessageType;
+  /** Message payload */
+  payload?: T;
+  /** Message timestamp (optional) */
+  timestamp?: number;
+}
+
+// ============================================
+// Specific Message Payloads
+// ============================================
+
+/**
+ * Blade context for chatbot (simplified for chat use)
+ */
+export interface IChatBladeContext {
+  /** Blade identifier */
+  id: string;
+  /** Blade component name */
+  name: string;
+  /** Blade display title */
+  title: string;
+  /** Route parameter (e.g., item ID being edited) */
+  param?: string;
+}
+
+/** Payload for INIT_CONTEXT message (Shell -> Chat) */
+export interface IInitContextPayload {
+  /** Current user ID */
+  userId: string;
+  /** User locale */
+  locale: string;
+  /** Tenant identifier (from JWT or host app) */
+  tenantId?: string;
+  /** Current blade context */
+  blade: IChatBladeContext;
+  /** Context type - determines chatbot UI behavior */
+  contextType: AiAgentContextType;
+  /** Data items - always array (1 for details, N for list) */
+  items: Record<string, unknown>[];
+  /** Custom suggestions (if any) */
+  suggestions?: ISuggestion[];
+  /** Access token for API calls (automatically refreshed) */
+  accessToken?: string;
+}
+
+/** Payload for UPDATE_CONTEXT message (Shell -> Chat) */
+export interface IUpdateContextPayload {
+  /** Updated blade context (if changed) */
+  blade?: IChatBladeContext;
+  /** Tenant identifier (from JWT or host app) */
+  tenantId?: string;
+  /** Context type - determines chatbot UI behavior */
+  contextType: AiAgentContextType;
+  /** Data items - always array of full objects */
+  items: Record<string, unknown>[];
+  /** Custom suggestions (if changed) */
+  suggestions?: ISuggestion[];
+  /** Updated user locale (if changed) */
+  locale?: string;
+  /** Access token for API calls (automatically refreshed) */
+  accessToken?: string;
+}
+
+/** Payload for NAVIGATE_TO_APP message (Chat -> Shell) */
+export interface INavigateToAppPayload {
+  /** Blade name to open */
+  bladeName: string;
+  /** Entity ID */
+  param?: string;
+  /** Additional options */
+  options?: Record<string, unknown>;
+}
+
+/** Payload for PREVIEW_CHANGES message (Chat -> Shell) */
+export interface IPreviewChangesPayload {
+  /** Updated data to preview */
+  data: Record<string, unknown>;
+  /** List of changed field names */
+  changedFields?: string[];
+}
+
+/** Payload for APPLY_CHANGES message (Chat -> Shell) */
+export interface IApplyChangesPayload {
+  changes: Array<{
+    entityId: string;
+    entityType: string;
+    field: string;
+    oldValue: unknown;
+    newValue: unknown;
+  }>;
+}
+
+/** Payload for DOWNLOAD_FILE message (Chat -> Shell) */
+export interface IDownloadFilePayload {
+  /** Filename for download */
+  filename: string;
+  /** MIME type */
+  contentType: string;
+  /** Base64 encoded content */
+  content: string;
+}
+
+/** Payload for CHAT_ERROR message (Chat -> Shell) */
+export interface IChatErrorPayload {
+  code: string;
+  message: string;
+}

package/core/plugins/modularity/index.ts

@@ -2,12 +2,14 @@ import { App, Component, h, inject, resolveComponent, watch } from "vue";
 import { i18n } from "./../i18n";
 import { Router } from "vue-router";
 import { BladeInstanceConstructor, BladeVNode } from "./../../../shared/components/blade-navigation/types";
-import { kebabToPascal } from "./../../utilities";
+import { kebabToPascal, createLogger } from "./../../utilities";
 import { addMenuItem, useMenuService, useNotifications } from "../../composables";
 import * as _ from "lodash-es";
 import { notification } from "../../../shared";
 import { BladeRegistryKey, IBladeRegistrationData, IBladeRegistryInstance } from "../../composables/useBladeRegistry";
 
+const logger = createLogger("modularity");
+
 export function createModule(components: { [key: string]: BladeInstanceConstructor }, locales?: unknown) {
   return {
     install(app: App): void {
@@ -17,7 +19,7 @@ export function createModule(components: { [key: string]: BladeInstanceConstruct
         if (app.component(componentName)) {
           // Remove the existing component
           // Note: Vue does not provide a method to remove a component, so we can overwrite it
-          console.warn(
+          logger.warn(
             `Component ${componentName} is already registered. It will be overwritten with the new component.`,
           );
         }
@@ -52,11 +54,11 @@ export function createAppModule(
       if (bladeRegistry && bladeRegistry._registerBladeFn) {
         registerBladeWithRegistry = bladeRegistry._registerBladeFn;
       } else {
-        console.error(
+        logger.error(
           "createAppModule: BladeRegistry or its _registerBladeFn not found via inject. Blade registration will be skipped.",
         );
         registerBladeWithRegistry = (name: string, data: IBladeRegistrationData) => {
-          console.warn(`BladeRegistry (noop): Tried to register '${name}' but _registerBladeFn is missing.`);
+          logger.warn(`BladeRegistry (noop): Tried to register '${name}' but _registerBladeFn is missing.`);
         };
       }
 
@@ -83,7 +85,7 @@ export function createAppModule(
               isWorkspace: page.isWorkspace || false,
             });
           } else {
-            console.warn(
+            logger.warn(
               "createAppModule: Page without URL is missing a name. Cannot register with BladeRegistry.",
               page,
             );
@@ -179,7 +181,7 @@ export function createAppModule(
           // Check if the component is already registered
           if (app.component(name)) {
             // Overwrite existing component
-            console.warn(`Component ${name} is already registered. It will be overwritten with the new component.`);
+            logger.warn(`Component ${name} is already registered. It will be overwritten with the new component.`);
           }
           app.component(name, component);
         });

package/core/plugins/modularity/loader.ts

@@ -3,6 +3,9 @@ import { Router } from "vue-router";
 import { DynamicModulesKey } from "../../../injection-keys";
 import * as semver from "semver";
 import { notification } from "../../../shared";
+import { createLogger } from "../../utilities";
+
+const logger = createLogger("module-loader");
 
 interface ModuleManifest {
   file: string;
@@ -108,12 +111,12 @@ async function loadVersionInfo(url: string): Promise<VersionInfo | null> {
   try {
     const response = await fetch(url);
     if (!response.ok) {
-      console.warn(`Failed to load version info: ${response.statusText}`);
+      logger.warn(`Failed to load version info: ${response.statusText}`);
       return null;
     }
     return (await response.json()) as VersionInfo;
   } catch (error) {
-    console.warn(`Error loading version info: ${error}`);
+    logger.warn(`Error loading version info: ${error}`);
     return null;
   }
 }
@@ -145,7 +148,7 @@ function checkVersionCompatibility(
     moduleVersion.compatibleWith.framework &&
     !semver.satisfies(frameworkVersion, moduleVersion.compatibleWith.framework, { includePrerelease: true })
   ) {
-    console.error(
+    logger.error(
       `Module ${moduleId} requires framework version ${moduleVersion.compatibleWith.framework}, but current framework version is ${frameworkVersion}.`,
     );
     notification.error(
@@ -163,12 +166,12 @@ function checkVersionCompatibility(
       const loadedDepVersion = loadedModulesWithVersions.get(depModuleId);
 
       if (!loadedDepVersion) {
-        console.warn(`Module ${moduleId} depends on ${depModuleId}, but it is not loaded yet.`);
+        logger.warn(`Module ${moduleId} depends on ${depModuleId}, but it is not loaded yet.`);
         continue;
       }
 
       if (!semver.satisfies(loadedDepVersion, versionRange, { includePrerelease: true })) {
-        console.error(
+        logger.error(
           `Module ${moduleId} requires ${depModuleId} version ${versionRange}, but loaded version is ${loadedDepVersion}.`,
         );
         notification.error(
@@ -233,7 +236,7 @@ export function useDynamicModules(
   const finalConfig = { ...DEFAULT_CONFIG, ...config };
 
   if (!config.frameworkVersion && finalConfig.frameworkVersion) {
-    console.warn(
+    logger.warn(
       `Framework version not specified in the configuration, using default ${finalConfig.frameworkVersion}. This may cause compatibility issues with modules.`,
     );
   }
@@ -272,7 +275,7 @@ export function useDynamicModules(
               manifest: (await response.json()) as Manifest,
             };
           } catch (error) {
-            console.error(error);
+            logger.error("Error loading module manifest:", error);
             return null;
           }
         });
@@ -303,12 +306,12 @@ export function useDynamicModules(
                   .filter((file) => file.file.endsWith(".css"))
                   .map((file) => loadCSS(moduleUrl + file.file)),
               ).catch((error) => {
-                console.error(`Failed to load styles for module ${moduleId}:`, error);
+                logger.error(`Failed to load styles for module ${moduleId}:`, error);
               }),
             ]);
 
             if (versionInfoFromFile) {
-              console.info(`Loaded version info for module ${moduleId}: v${versionInfoFromFile.version}`);
+              logger.info(`Loaded version info for module ${moduleId}: v${versionInfoFromFile.version}`);
             }
 
             // Import module
@@ -322,7 +325,7 @@ export function useDynamicModules(
               success: true,
             };
           } catch (error) {
-            console.error(`Failed to load module ${moduleId}:`, error);
+            logger.error(`Failed to load module ${moduleId}:`, error);
             return {
               moduleId,
               moduleUrl,
@@ -342,7 +345,7 @@ export function useDynamicModules(
           moduleLoadResults.filter((result) => result.success).map((result) => [result.moduleId, result]),
         );
 
-        console.log("🔍 LoadResultsMap keys:", Array.from(loadResultsMap.keys()));
+        logger.debug("LoadResultsMap keys:", Array.from(loadResultsMap.keys()));
 
         // Wait for all modules to register themselves in the global scope
         const expectedModuleIds = Array.from(loadResultsMap.keys());
@@ -369,9 +372,9 @@ export function useDynamicModules(
 
         // Check if modules are already registered
         if (areAllModulesRegistered()) {
-          console.log("✅ All modules are already registered, proceeding with installation");
+          logger.debug("All modules are already registered, proceeding with installation");
         } else {
-          console.log(`🔍 Waiting for ${expectedModuleIds.length} modules to register:`, expectedModuleIds);
+          logger.debug(`Waiting for ${expectedModuleIds.length} modules to register:`, expectedModuleIds);
 
           // Wait for module registration with timeout
           await new Promise<void>((resolve) => {
@@ -392,7 +395,7 @@ export function useDynamicModules(
 
             const checkAndResolve = () => {
               if (areAllModulesRegistered()) {
-                console.log("✅ All modules are registered, proceeding with installation");
+                logger.debug("All modules are registered, proceeding with installation");
                 cleanup();
                 resolve();
                 return true;
@@ -410,8 +413,8 @@ export function useDynamicModules(
             const poll = async () => {
               while (attempts < maxAttempts) {
                 const availableModules = getAvailableModules();
-                console.log(
-                  `🔍 Attempt ${attempts + 1}: Available modules:`,
+                logger.debug(
+                  `Attempt ${attempts + 1}: Available modules:`,
                   availableModules,
                   `(${availableModules.length}/${expectedModuleIds.length})`,
                 );
@@ -422,7 +425,7 @@ export function useDynamicModules(
                 await new Promise((r) => setTimeout(r, 100));
               }
 
-              console.warn("⚠️ Timeout waiting for all modules to register, proceeding with available modules");
+              logger.warn("Timeout waiting for all modules to register, proceeding with available modules");
               cleanup();
               resolve();
             };
@@ -441,18 +444,18 @@ export function useDynamicModules(
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const modulesToProcess: [string, any][] = Object.entries(window.VcShellDynamicModules || {});
 
-        console.log(
-          `🚀 Found ${modulesToProcess.length} modules to process:`,
+        logger.debug(
+          `Found ${modulesToProcess.length} modules to process:`,
           modulesToProcess.map(([name]) => name),
         );
 
         for (const [moduleName, moduleObject] of modulesToProcess) {
           if (loadedModules.has(moduleName)) {
-            console.log(`⏭️ Skipping already loaded module: ${moduleName}`);
+            logger.debug(`Skipping already loaded module: ${moduleName}`);
             continue;
           }
 
-          console.log(`📦 Processing module: ${moduleName}`);
+          logger.debug(`Processing module: ${moduleName}`);
 
           // Try to find the corresponding load result by matching module names
           const loadResult =
@@ -469,16 +472,16 @@ export function useDynamicModules(
 
           const mainModule = getModuleInstall(moduleObject);
 
-          console.log(`🔍 Module ${moduleName} exports:`, Object.keys(moduleObject));
-          console.log(`🔍 Module ${moduleName} has install function:`, !!mainModule);
+          logger.debug(`Module ${moduleName} exports:`, Object.keys(moduleObject));
+          logger.debug(`Module ${moduleName} has install function:`, !!mainModule);
 
           if (mainModule) {
             const moduleVersionInfo = (mainModule as ModuleWithNamedExport).version || versionFromFile;
 
             try {
               if (!finalConfig.skipVersionCheck) {
-                console.log(
-                  `🔎 Checking compatibility for ${moduleName} (version: ${moduleVersionInfo?.version || "N/A"})`,
+                logger.debug(
+                  `Checking compatibility for ${moduleName} (version: ${moduleVersionInfo?.version || "N/A"})`,
                 );
                 checkVersionCompatibility(
                   moduleName,
@@ -488,7 +491,7 @@ export function useDynamicModules(
                 );
               }
 
-              console.log(`🔧 Installing module: ${moduleName}`, {
+              logger.debug(`Installing module: ${moduleName}`, {
                 hasLoadResult: !!loadResult,
                 versionFromFile: versionFromFile?.version,
                 moduleVersion: moduleVersionInfo?.version,
@@ -503,31 +506,31 @@ export function useDynamicModules(
                 loadedModulesWithVersions.set(moduleName, moduleVersionInfo.version);
               }
 
-              console.log(
-                `✅ Module ${moduleName} installed successfully (version: ${
+              logger.info(
+                `Module ${moduleName} installed successfully (version: ${
                   moduleVersionInfo?.version || "no version info"
                 })`,
               );
             } catch (e) {
               if (e instanceof VersionCompatibilityError) {
-                console.error(`Compatibility error in module ${e.moduleId}:`, e.details);
+                logger.error(`Compatibility error in module ${e.moduleId}:`, e.details);
               } else {
-                console.error(`Failed to install module ${moduleName}:`, e);
+                logger.error(`Failed to install module ${moduleName}:`, e);
                 notification.error(`Failed to install module ${moduleName}`);
               }
             }
           } else {
-            console.error(`❌ Module ${moduleName} does not have an 'install' function`);
+            logger.error(`Module ${moduleName} does not have an 'install' function`);
             notification.error(
               `Module ${moduleName} is not a valid module because it does not have an 'install' function.`,
             );
           }
         }
 
-        console.log("🏁 Final loadedModules set:", Array.from(loadedModules));
+        logger.debug("Final loadedModules set:", Array.from(loadedModules));
       }
     } catch (error) {
-      console.error("Failed to load modules:", error);
+      logger.error("Failed to load modules:", error);
     }
 
     app.config.globalProperties.$dynamicModules = {

package/core/plugins/signalR/index.ts

@@ -4,6 +4,9 @@ import { PushNotification } from "../../api/platform";
 import { useNotifications } from "./../../composables/useNotifications";
 import { useUserManagement } from "../../composables/useUserManagement";
 import { useCypressSignalRMock } from "cypress-signalr-mock";
+import { createLogger } from "../../utilities";
+
+const logger = createLogger("signalR");
 
 const { addNotification } = useNotifications();
 const currentCreator = ref<string | undefined>();
@@ -17,7 +20,7 @@ function setupSystemEventsHandler(connection: any, creator?: string) {
 
   // Subscribe to events with the new creator
   if (creator) {
-    console.log("[SignalR] Setup handler for creator: ", creator);
+    logger.debug("Setup handler for creator: ", creator);
     connection.on("SendSystemEvents", (message: PushNotification) => {
       if (message.creator === creator) {
         addNotification(message);
@@ -48,11 +51,11 @@ export const signalR = {
       connection
         .start()
         .then(() => {
-          console.log("[SignalR] Connected.");
+          logger.info("Connected.");
           setupSystemEventsHandler(connection, currentCreator.value);
         })
         .catch((err) => {
-          console.log("[SignalR] Connection Error: ", err);
+          logger.error("Connection Error: ", err);
           setTimeout(() => start(), 5000);
         });
     };

package/core/services/app-bar-menu-service.ts

@@ -1,4 +1,7 @@
 import { ref, computed, Component, ComputedRef } from "vue";
+import { createLogger } from "../utilities";
+
+const logger = createLogger("app-bar-widget-service");
 
 export interface AppBarWidget {
   id: string;
@@ -75,7 +78,7 @@ export function createAppBarWidgetService(): IAppBarWidgetService {
     try {
       register(item);
     } catch (e) {
-      console.warn(`Failed to register pre-added AppBar widget ${item.id}:`, e);
+      logger.warn(`Failed to register pre-added AppBar widget ${item.id}:`, e);
     }
   });
 

package/core/services/dashboard-service.ts

@@ -1,6 +1,9 @@
 import { reactive, Component } from "vue";
 import { DashboardServiceKey } from "../../injection-keys";
 import { usePermissions } from "../composables/usePermissions";
+import { createLogger } from "../utilities";
+
+const logger = createLogger("dashboard-service");
 
 export interface DashboardWidgetSize {
   width: number;
@@ -102,7 +105,7 @@ export function createDashboardService(): IDashboardService {
     try {
       registerWidget(widget);
     } catch (e) {
-      console.warn(`Failed to register preregistered widget ${widget.id}:`, e);
+      logger.warn(`Failed to register preregistered widget ${widget.id}:`, e);
     }
   });
 

package/core/services/index.ts

@@ -7,3 +7,5 @@ export * from "./menu-service";
 export * from "./settings-menu-service";
 export * from "./toolbar-service";
 export * from "./widget-service";
+// blade-selection-service and ai-agent-service are now part of the ai-agent plugin
+// export * from "./core/plugins/ai-agent";