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

package/core/plugins/ai-agent/composables/useAiAgentContext.ts

@@ -0,0 +1,280 @@
+import { inject, ref, computed, watch, onUnmounted, type Ref, type ComputedRef } from "vue";
+import { mergeWith, isPlainObject } from "lodash-es";
+import { AiAgentServiceKey, BladeInstanceKey } from "../../../../injection-keys";
+import type { IAiAgentServiceInternal } from "../services/ai-agent-service";
+import type {
+  ISuggestion,
+  UseAiAgentContextOptions,
+  UseAiAgentContextReturn,
+  IPreviewChangesPayload,
+  AiAgentContextType,
+} from "../types";
+import { createLogger } from "../../../utilities";
+
+const logger = createLogger("use-ai-agent-context");
+
+/**
+ * Custom merge function for AI agent preview changes.
+ * Handles sparse arrays where null means "skip this index".
+ *
+ * @example
+ * // Nested objects - deep merge
+ * deepMergeChanges({seo: {title: "Old", desc: "Desc"}}, {seo: {title: "New"}})
+ * // → {seo: {title: "New", desc: "Desc"}}
+ *
+ * @example
+ * // Sparse arrays - null skips index
+ * deepMergeChanges({items: [{a:1}, {b:2}]}, {items: [null, {c:3}]})
+ * // → {items: [{a:1}, {b:2, c:3}]}
+ */
+function deepMergeChanges<T extends object>(target: T, source: object): T {
+  const customizer = (targetVal: unknown, sourceVal: unknown): unknown => {
+    // If source value is null/undefined, keep target value (skip this index/field)
+    if (sourceVal === null || sourceVal === undefined) {
+      return targetVal;
+    }
+
+    // If both are arrays, merge by index with sparse array support
+    if (Array.isArray(targetVal) && Array.isArray(sourceVal)) {
+      const result = [...targetVal];
+      sourceVal.forEach((item, index) => {
+        if (item !== null && item !== undefined) {
+          if (isPlainObject(item) && isPlainObject(result[index])) {
+            // Recursively merge objects in array
+            result[index] = deepMergeChanges(result[index] as object, item);
+          } else {
+            // Replace primitive or non-object values
+            result[index] = item;
+          }
+        }
+        // null/undefined in source array = skip this index
+      });
+      return result;
+    }
+
+    // For objects, let mergeWith handle recursively with this customizer
+    return undefined;
+  };
+
+  return mergeWith({}, target, source, customizer);
+}
+
+/**
+ * Checks if the ref value is an array
+ */
+function isArrayRef<T>(dataRef: Ref<T> | Ref<T[]>): dataRef is Ref<T[]> {
+  return Array.isArray(dataRef.value);
+}
+
+/**
+ * Normalizes any ref value to an array for sending to the AI agent
+ */
+function normalizeToArray<T>(value: T | T[]): T[] {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return value != null ? [value] : [];
+}
+
+/**
+ * Gets the target object for applying changes based on ref type
+ */
+function getTargetForChanges<T>(dataRef: Ref<T> | Ref<T[]>): T | undefined {
+  if (isArrayRef(dataRef)) {
+    // Array ref - return first item
+    return dataRef.value[0];
+  }
+  // Single object ref - return the object directly
+  return dataRef.value;
+}
+
+/**
+ * Composable for binding blade data to AI agent context.
+ *
+ * This composable automatically:
+ * - Sends data updates to the AI agent when dataRef changes
+ * - Normalizes single objects to arrays for the AI agent
+ * - Handles PREVIEW_CHANGES messages to update form data
+ * - Provides preview state for visual feedback
+ *
+ * @example List blade (array of selected items)
+ * ```typescript
+ * const { selectedItems } = useTableSelection<Offer>();
+ *
+ * useAiAgentContext({ dataRef: selectedItems });
+ * ```
+ *
+ * @example Details blade (single object - automatically wrapped in array)
+ * ```typescript
+ * const offer = ref<Offer>({});
+ *
+ * // Just pass the ref directly - no need to wrap in array!
+ * const { previewState } = useAiAgentContext({ dataRef: offer });
+ *
+ * // Use previewState.isActive to show preview indicator
+ * ```
+ *
+ * @example With custom suggestions
+ * ```typescript
+ * useAiAgentContext({
+ *   dataRef: offer,
+ *   suggestions: [
+ *     {
+ *       id: "translate",
+ *       title: "Translate description",
+ *       icon: "translation",
+ *       iconColor: "#FF4A4A",
+ *       prompt: "Translate the offer description to English"
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export function useAiAgentContext<T extends { id: string; objectType: string; name: string; [key: string]: unknown }>(
+  options: UseAiAgentContextOptions<T>,
+): UseAiAgentContextReturn {
+  const { dataRef, suggestions } = options;
+
+  // Try to get the service (may not be available if plugin not installed)
+  const service = inject(AiAgentServiceKey) as IAiAgentServiceInternal | undefined;
+
+  // Get current blade instance to identify which blade this context belongs to
+  const bladeInstance = inject(BladeInstanceKey, null);
+  const bladeId = computed(() => bladeInstance?.value?.id);
+
+  // Preview state
+  const isPreviewActive = ref(false);
+  const changedFieldsList = ref<string[]>([]);
+
+  // If service is not available, return dummy preview state
+  if (!service) {
+    logger.debug("AiAgentService not available, context binding disabled");
+    return {
+      previewState: {
+        isActive: computed(() => false),
+        changedFields: computed(() => []),
+      },
+    };
+  }
+
+  // Determine context type based on dataRef type
+  // Array ref = list blade (multiple selected items)
+  // Single object ref = details blade (single item being edited)
+  const detectedContextType: AiAgentContextType = isArrayRef(dataRef) ? "list" : "details";
+
+  // Set context data in service (items, contextType, and suggestions)
+  // Always sends an array to the service, normalizing single objects
+  // Context is bound to specific blade ID
+  const updateContextData = () => {
+    const items = normalizeToArray(dataRef.value).map((item) => ({
+      id: item.id,
+      objectType: item.objectType,
+      name: item.name,
+    }));
+    service._setContextData(items, detectedContextType, suggestions, bladeId.value);
+    console.log(
+      `[USE-AI-AGENT-CONTEXT] Context updated: ${items.length} items, type: ${detectedContextType}, blade: ${bladeId.value}`,
+    );
+  };
+
+  // Log that the handler is being registered
+  console.log("[USE-AI-AGENT-CONTEXT] Registering PREVIEW_CHANGES handler for blade:", bladeId.value);
+
+  // Watch dataRef for changes and update context
+  const stopWatch = watch(
+    dataRef,
+    () => {
+      updateContextData();
+      // Clear preview state when data changes from outside
+      if (isPreviewActive.value) {
+        isPreviewActive.value = false;
+        changedFieldsList.value = [];
+      }
+    },
+    { deep: true, immediate: true },
+  );
+
+  // Handle PREVIEW_CHANGES messages
+  // Applies changes to the target object (single ref or first item in array)
+  const unsubscribe = service._onPreviewChanges((payload: IPreviewChangesPayload) => {
+    console.log("[USE-AI-AGENT-CONTEXT] PREVIEW_CHANGES handler called", {
+      bladeId: bladeId.value,
+      payloadKeys: Object.keys(payload.data || {}),
+      changedFields: payload.changedFields,
+      hasDataRef: !!dataRef,
+      dataRefValue: dataRef?.value ? "present" : "empty",
+    });
+
+    const target = getTargetForChanges(dataRef);
+    if (!target) {
+      console.warn("[USE-AI-AGENT-CONTEXT] Cannot apply preview changes: no data in dataRef", {
+        bladeId: bladeId.value,
+        dataRefValue: dataRef?.value,
+      });
+      return;
+    }
+
+    const targetObj = target as Record<string, unknown>;
+    const updatedData = payload.data;
+
+    console.log("[USE-AI-AGENT-CONTEXT] Applying preview changes", {
+      bladeId: bladeId.value,
+      targetObjKeys: Object.keys(targetObj),
+      updatedDataKeys: Object.keys(updatedData),
+      updatedDataPreview: JSON.stringify(updatedData).substring(0, 500),
+    });
+
+    // Deep merge changes into target object
+    // Supports:
+    // - Nested objects: {"seo": {"metaTitle": "New"}} merges into existing seo
+    // - Sparse arrays: [null, {"price": 50}] updates index 1 only (null = skip)
+    const mergedResult = deepMergeChanges(targetObj, updatedData);
+
+    // Copy merged result back to target object (to trigger Vue reactivity)
+    Object.keys(mergedResult).forEach((key) => {
+      targetObj[key] = mergedResult[key as keyof typeof mergedResult];
+    });
+
+    console.log("[USE-AI-AGENT-CONTEXT] Deep merge completed", {
+      bladeId: bladeId.value,
+      resultPreview: JSON.stringify(targetObj).substring(0, 500),
+    });
+
+    // Update preview state
+    isPreviewActive.value = true;
+    changedFieldsList.value = payload.changedFields || Object.keys(updatedData);
+
+    console.log("[USE-AI-AGENT-CONTEXT] Preview changes applied successfully", {
+      bladeId: bladeId.value,
+      changedFields: changedFieldsList.value,
+      isPreviewActive: isPreviewActive.value,
+      targetObjAfter: JSON.stringify(targetObj).substring(0, 500),
+    });
+  });
+
+  // Cleanup on unmount
+  onUnmounted(() => {
+    stopWatch();
+    unsubscribe();
+    // Clear context for this specific blade when component unmounts
+    service._setContextData([], "list", undefined, bladeId.value);
+    logger.debug(`Context cleared on unmount for blade: ${bladeId.value}`);
+  });
+
+  return {
+    previewState: {
+      isActive: computed(() => isPreviewActive.value),
+      changedFields: computed(() => changedFieldsList.value),
+    },
+  };
+}
+
+/**
+ * Clears the preview state manually.
+ * Useful when user saves or discards changes.
+ */
+export function clearPreviewState(previewState: UseAiAgentContextReturn["previewState"]): void {
+  // This is a helper for external clearing if needed
+  // The actual state is cleared when dataRef changes
+  logger.debug("Preview state cleared manually");
+}

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

@@ -0,0 +1,89 @@
+import type { IAiAgentConfig, ISuggestion } from "./types";
+
+/**
+ * Default configuration for AI agent panel
+ */
+export const DEFAULT_AI_AGENT_CONFIG: IAiAgentConfig = {
+  url: "",
+  title: "Virto OZ",
+  width: 350,
+  expandedWidth: 500,
+  allowedOrigins: ["*"],
+};
+
+/**
+ * Environment variable name for AI agent URL
+ */
+export const AI_AGENT_URL_ENV_KEY = "APP_AI_AGENT_URL";
+
+/**
+ * Message types for Shell -> Chat communication
+ */
+export const SHELL_TO_CHAT_MESSAGE_TYPES = {
+  INIT_CONTEXT: "INIT_CONTEXT",
+  UPDATE_CONTEXT: "UPDATE_CONTEXT",
+} as const;
+
+/**
+ * Message types for Chat -> Shell communication
+ */
+export const CHAT_TO_SHELL_MESSAGE_TYPES = {
+  CHAT_READY: "CHAT_READY",
+  NAVIGATE_TO_APP: "NAVIGATE_TO_APP",
+  EXPAND_IN_CHAT: "EXPAND_IN_CHAT",
+  RELOAD_BLADE: "RELOAD_BLADE",
+  PREVIEW_CHANGES: "PREVIEW_CHANGES",
+  APPLY_CHANGES: "APPLY_CHANGES",
+  DOWNLOAD_FILE: "DOWNLOAD_FILE",
+  SHOW_MORE: "SHOW_MORE",
+  CHAT_ERROR: "CHAT_ERROR",
+} as const;
+
+/**
+ * Default suggestions when no custom suggestions provided
+ */
+export const DEFAULT_SUGGESTIONS: ISuggestion[] = [
+  {
+    id: "generate-report",
+    title: "Generate a report",
+    icon: "analytics-01",
+    iconColor: "#57AB79",
+    prompt: "Generate a report",
+  },
+  {
+    id: "find-sales",
+    title: "Find sales statistics",
+    icon: "progress-02",
+    iconColor: "#FFBA35",
+    prompt: "Find sales statistics",
+  },
+  {
+    id: "translate",
+    title: "Translate description",
+    icon: "translation",
+    iconColor: "#FF4A4A",
+    prompt: "Translate description",
+  },
+  {
+    id: "top-sales",
+    title: "Find top sales report",
+    icon: "analytics-up",
+    iconColor: "#319ED4",
+    prompt: "Find top sales report",
+  },
+];
+
+/**
+ * Default toolbar button ID for AI agent
+ */
+export const AI_AGENT_TOOLBAR_BUTTON_ID = "ai-agent-toggle";
+
+/**
+ * Default toolbar button icon
+ */
+export const AI_AGENT_TOOLBAR_BUTTON_ICON = "lucide-sparkles";
+
+/**
+ * Default toolbar button title
+ */
+export const AI_AGENT_TOOLBAR_BUTTON_TITLE = "AI Assistant";

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

@@ -0,0 +1,91 @@
+import type { App } from "vue";
+import type { IAiAgentConfig } from "./types";
+import { DEFAULT_AI_AGENT_CONFIG, AI_AGENT_URL_ENV_KEY } from "./constants";
+import { createLogger } from "../../utilities";
+
+const logger = createLogger("ai-agent-plugin");
+
+/**
+ * Options for the AI Agent Plugin
+ */
+export interface AiAgentPluginOptions {
+  /**
+   * AI Agent configuration.
+   * URL can also be set via APP_AI_AGENT_URL environment variable.
+   */
+  config?: Partial<IAiAgentConfig>;
+
+  /**
+   * Whether to add the AI button to all blade toolbars automatically.
+   * Default: true
+   */
+  addGlobalToolbarButton?: boolean;
+}
+
+/**
+ * Vue plugin for AI Agent integration.
+ *
+ * @example
+ * ```typescript
+ * import { createApp } from "vue";
+ * import { aiAgentPlugin } from "@vc-shell/framework";
+ *
+ * const app = createApp(App);
+ *
+ * // Install with options
+ * app.use(aiAgentPlugin, {
+ *   config: {
+ *     title: "AI Assistant",
+ *     width: 400,
+ *   },
+ *   addGlobalToolbarButton: true,
+ * });
+ * ```
+ */
+export const aiAgentPlugin = {
+  install(app: App, options: AiAgentPluginOptions = {}) {
+    const { config = {}, addGlobalToolbarButton = true } = options;
+
+    // Get URL from environment variable if not provided
+    let url = config.url || "";
+    if (!url && typeof import.meta !== "undefined" && import.meta.env) {
+      url = import.meta.env[AI_AGENT_URL_ENV_KEY] || "";
+    }
+
+    // Skip installation if no URL configured
+    if (!url) {
+      logger.info("AI Agent plugin skipped: no URL configured. Set APP_AI_AGENT_URL env variable or pass config.url option.");
+      return;
+    }
+
+    // Merge config with defaults
+    const finalConfig: IAiAgentConfig = {
+      ...DEFAULT_AI_AGENT_CONFIG,
+      ...config,
+      url,
+    };
+
+    // Store config in app global properties for access during service creation
+    app.config.globalProperties.$aiAgentConfig = finalConfig;
+    app.provide("aiAgentConfig", finalConfig);
+    app.provide("aiAgentAddGlobalToolbarButton", addGlobalToolbarButton);
+
+    logger.info(`AI Agent plugin installed. URL: ${url}, addGlobalToolbarButton: ${addGlobalToolbarButton}`);
+  },
+};
+
+// Re-export all types
+export * from "./types";
+export * from "./constants";
+
+// Re-export composables
+export { useAiAgent, provideAiAgentService, createAiAgentToolbarButton } from "./composables/useAiAgent";
+export type { UseAiAgentReturn, ProvideAiAgentServiceOptions } from "./composables/useAiAgent";
+
+export { useAiAgentContext, clearPreviewState } from "./composables/useAiAgentContext";
+
+// Re-export components
+export { VcAiAgentPanel } from "./components";
+
+// Re-export service types
+export type { IAiAgentServiceInternal, CreateAiAgentServiceOptions } from "./services/ai-agent-service";