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

package/core/composables/useWidgets/index.ts

@@ -6,6 +6,9 @@ import {
   registerExternalWidget,
 } from "./../../services/widget-service";
 import { WidgetServiceKey } from "./../../../injection-keys";
+import { createLogger, InjectionError } from "../../utilities";
+
+const logger = createLogger("use-widgets");
 
 export function provideWidgetService(): IWidgetService {
   const service = createWidgetService();
@@ -16,8 +19,8 @@ export function provideWidgetService(): IWidgetService {
 export function useWidgets(): IWidgetService {
   const service = inject(WidgetServiceKey);
   if (!service) {
-    console.error("Widget service not found in current context. Injection chain:", getCurrentInstance());
-    throw new Error("WidgetService not provided");
+    logger.error("Widget service not found in current context. Injection chain:", getCurrentInstance());
+    throw new InjectionError("WidgetService");
   }
   return service;
 }

package/core/constants/defaults.ts

@@ -0,0 +1,76 @@
+/**
+ * Component Default Values for VC-Shell Framework
+ * Centralized storage for default prop values across components
+ */
+
+export const COMPONENT_DEFAULTS = {
+  input: {
+    maxlength: 1024,
+    debounce: 0,
+    type: "text" as const,
+    autocomplete: "off" as const,
+  },
+
+  select: {
+    debounce: 500,
+    pageSize: 20,
+    searchable: true,
+    clearable: true,
+  },
+
+  table: {
+    pageSize: 20,
+    pageSizes: [10, 20, 50, 100] as readonly number[],
+    selectable: false,
+    multiselect: false,
+    stickyHeader: true,
+  },
+
+  pagination: {
+    pageSize: 20,
+    visiblePages: 5,
+  },
+
+  textarea: {
+    rows: 3,
+    maxlength: 4096,
+  },
+
+  editor: {
+    minHeight: 200,
+    maxHeight: 500,
+  },
+
+  tooltip: {
+    delay: 300,
+    placement: "top" as const,
+  },
+
+  modal: {
+    closeOnEscape: true,
+    closeOnOverlayClick: true,
+  },
+
+  notification: {
+    duration: 5000,
+    position: "top-right" as const,
+  },
+
+  dashboard: {
+    columns: 12,
+    rowHeight: 80,
+    gap: 20,
+  },
+} as const;
+
+/**
+ * Type for accessing component defaults
+ */
+export type ComponentDefaults = typeof COMPONENT_DEFAULTS;
+
+/**
+ * Helper to get defaults for a specific component
+ */
+export function getComponentDefaults<K extends keyof ComponentDefaults>(componentName: K): ComponentDefaults[K] {
+  return COMPONENT_DEFAULTS[componentName];
+}

package/core/constants/index.ts

@@ -1,3 +1,5 @@
 export const FALLBACK_BLADE_ID = "fallback-blade-id";
 
 export * from "./locale";
+export * from "./ui";
+export * from "./defaults";

package/core/constants/ui.ts

@@ -0,0 +1,68 @@
+/**
+ * UI Constants for VC-Shell Framework
+ * Centralized storage for magic numbers and UI-related constants
+ */
+
+export const UI_CONSTANTS = {
+  // Grid system
+  GRID_COLUMNS: 12,
+  CELL_HEIGHT: 80,
+  WIDGET_GAP: 20,
+
+  // Timing (milliseconds)
+  DEBOUNCE_DEFAULT_MS: 500,
+  HOVER_DELAY_MS: 200,
+  TOOLTIP_DELAY_MS: 300,
+  RESIZE_DEBOUNCE_MS: 100,
+  ANIMATION_DURATION_MS: 200,
+  TRANSITION_DURATION_MS: 150,
+
+  // Thresholds
+  DRAG_THRESHOLD_PX: 3,
+  MAX_COLLISION_ITERATIONS: 50,
+  MIN_COLUMN_WIDTH_PX: 15,
+  OVERFLOW_THRESHOLD: 100,
+
+  // Z-index layers
+  Z_INDEX: {
+    DROPDOWN: 100,
+    TOOLTIP: 9999,
+    POPUP: 10000,
+    MODAL: 10001,
+    DRAG: 1000,
+    SIDEBAR: 50,
+    HEADER: 40,
+  },
+
+  // Pagination
+  PAGINATION_VISIBLE_PAGES: 5,
+  PAGINATION_EDGE_PAGES: 3,
+
+  // Table
+  TABLE_ROW_HEIGHT: 48,
+  TABLE_HEADER_HEIGHT: 56,
+
+  // Input
+  DEFAULT_MAXLENGTH: 1024,
+  DEFAULT_TEXTAREA_ROWS: 3,
+
+  // Menu
+  MENU_COLLAPSED_WIDTH: 76,
+  MENU_EXPANDED_WIDTH: 246,
+  MENU_ITEM_HEIGHT: 38,
+
+  // Breakpoints (pixels)
+  BREAKPOINTS: {
+    XS: 0,
+    SM: 576,
+    MD: 768,
+    LG: 992,
+    XL: 1200,
+    XXL: 1400,
+  },
+} as const;
+
+/**
+ * Type for accessing UI constants values
+ */
+export type UIConstants = typeof UI_CONSTANTS;

package/core/interceptors/index.ts

@@ -2,6 +2,9 @@
 import { Router } from "vue-router";
 import { useUserManagement } from "../composables/useUserManagement";
 import { notification } from "../../shared";
+import { createLogger } from "../utilities";
+
+const logger = createLogger("interceptors");
 
 export function registerInterceptors(router: Router) {
   const { fetch: originalFetch } = window;
@@ -16,8 +19,8 @@ export function registerInterceptors(router: Router) {
      * @returns A promise that resolves to the response from the API call.
      */
     if (window.__DEMO_MODE__) {
-      console.warn("CANCELLED FETCH WHILE IN __DEMO_MODE__: ", ...args);
-      console.warn("Please logout and add APP_PLATFORM_URL into .env file of your application to enable API calls");
+      logger.warn("CANCELLED FETCH WHILE IN __DEMO_MODE__: ", ...args);
+      logger.warn("Please logout and add APP_PLATFORM_URL into .env file of your application to enable API calls");
       return new Promise((resolve: any) => {
         /**
          * This conditions are mocking login, currentuser API calls for demo purposes.

package/core/plugins/ai-agent/README.md

@@ -0,0 +1,336 @@
+# AI Agent Plugin for VC-Shell
+
+A Vue plugin for integrating an AI assistant panel into VC-Shell applications.
+
+## Features
+
+- ENV-based configuration (`APP_AI_AGENT_URL`)
+- Automatic AI button in blade toolbars (via wildcard "*" support)
+- Two operation modes:
+  - **List blade** - batch operations with multiple selected items
+  - **Details blade** - single object editing with preview
+- Custom suggestions per blade
+- Reactive data binding between blade and agent
+- Simple integration API with minimal boilerplate
+
+## Installation
+
+### 1. Set Environment Variable
+
+```env
+APP_AI_AGENT_URL=https://your-ai-agent-url.com
+```
+
+### 2. Install Plugin in main.ts
+
+```typescript
+import { createApp } from "vue";
+import { aiAgentPlugin } from "@vc-shell/framework";
+
+const app = createApp(App);
+
+// Install with options (optional)
+app.use(aiAgentPlugin, {
+  config: {
+    title: "AI Assistant",
+    width: 400,
+  },
+  addGlobalToolbarButton: true, // default: true
+});
+```
+
+## Usage
+
+### List Blade (Batch Operations)
+
+```typescript
+// offers-list.vue
+import { ref, watch } from "vue";
+import { useAiAgentContext } from "@vc-shell/framework";
+
+const selectedOffers = ref<IOffer[]>([]);
+
+// Connect to AI agent
+useAiAgentContext({ dataRef: selectedOffers });
+
+// When table selection changes, pass full objects
+const onSelectionChanged = (items: IOffer[]) => {
+  selectedOffers.value = items;
+};
+```
+
+### Details Blade (Single Object)
+
+```typescript
+// offers-details.vue
+import { ref, watch } from "vue";
+import { useAiAgentContext } from "@vc-shell/framework";
+
+const offer = ref<IOffer>({});
+const aiData = ref<IOffer[]>([]); // Always array!
+
+// Sync single object to array
+watch(
+  offer,
+  (val) => {
+    aiData.value = val ? [val] : [];
+  },
+  { deep: true, immediate: true }
+);
+
+// Connect to AI agent with preview support
+const { previewState } = useAiAgentContext({ dataRef: aiData });
+
+// Use previewState.isActive to show preview indicator
+// Use previewState.changedFields to highlight changed fields
+```
+
+### Custom Suggestions
+
+```typescript
+useAiAgentContext({
+  dataRef: aiData,
+  suggestions: [
+    {
+      id: "translate",
+      title: "Translate description",
+      icon: "translation",
+      iconColor: "#FF4A4A",
+      prompt: "Translate the offer description to English",
+    },
+    {
+      id: "seo",
+      title: "Optimize SEO",
+      icon: "search",
+      iconColor: "#57AB79",
+      prompt: "Optimize SEO for this offer",
+    },
+  ],
+});
+```
+
+### Manual Panel Control
+
+```typescript
+import { useAiAgent } from "@vc-shell/framework";
+
+const { togglePanel, isOpen, openPanel, closePanel } = useAiAgent();
+
+// Toggle AI panel
+const handleAiClick = () => togglePanel();
+
+// Listen for messages from AI agent
+const { onMessage } = useAiAgent();
+onMessage((message) => {
+  if (message.type === "PREVIEW_CHANGES") {
+    // Handle preview changes
+  }
+});
+```
+
+## API Reference
+
+### aiAgentPlugin
+
+Vue plugin for AI agent integration.
+
+**Options:**
+
+| Option                  | Type                      | Default | Description                      |
+| ----------------------- | ------------------------- | ------- | -------------------------------- |
+| `config`                | `Partial<IAiAgentConfig>` | `{}`    | AI agent configuration           |
+| `addGlobalToolbarButton` | `boolean`                 | `true`  | Add AI button to all toolbars    |
+
+### useAiAgentContext
+
+Composable for binding blade data to AI agent context.
+
+**Options:**
+
+```typescript
+interface UseAiAgentContextOptions<T = Record<string, unknown>> {
+  /**
+   * Ref with data - ALWAYS an array:
+   * - For DETAILS blade: array with single object [item]
+   * - For LIST blade: array of selected objects [item1, item2, ...]
+   */
+  dataRef: Ref<T[]>;
+
+  /** Custom suggestions for this blade */
+  suggestions?: ISuggestion[];
+}
+```
+
+**Returns:**
+
+```typescript
+interface UseAiAgentContextReturn {
+  previewState: {
+    isActive: ComputedRef<boolean>;
+    changedFields: ComputedRef<string[]>;
+  };
+}
+```
+
+### useAiAgent
+
+Composable for panel control and communication.
+
+**Returns:**
+
+```typescript
+interface UseAiAgentReturn {
+  panelState: Ref<"closed" | "open" | "expanded">;
+  config: Ref<IAiAgentConfig>;
+  context: ComputedRef<IAiAgentContext>;
+  isOpen: ComputedRef<boolean>;
+  isExpanded: ComputedRef<boolean>;
+  totalItemsCount: ComputedRef<number>;
+  openPanel: () => void;
+  closePanel: () => void;
+  togglePanel: () => void;
+  expandPanel: () => void;
+  collapsePanel: () => void;
+  setConfig: (config: Partial<IAiAgentConfig>) => void;
+  sendMessage: (type: AiAgentMessageType, payload: unknown) => void;
+  onMessage: (handler: (event: IAiAgentMessage) => void) => () => void;
+}
+```
+
+### ISuggestion
+
+Custom suggestion card interface.
+
+```typescript
+interface ISuggestion {
+  id: string;
+  title: string;
+  icon: string;
+  iconColor?: string;
+  prompt: string;
+}
+```
+
+## PostMessage Protocol
+
+### Shell -> Agent
+
+**INIT_CONTEXT** (on panel open)
+
+```typescript
+{
+  type: "INIT_CONTEXT",
+  payload: {
+    userId: string,
+    locale: string,
+    blade: { id, name, title, param },
+    items: Record<string, unknown>[], // Always array
+    suggestions?: ISuggestion[],
+  }
+}
+```
+
+**UPDATE_CONTEXT** (on changes)
+
+```typescript
+{
+  type: "UPDATE_CONTEXT",
+  payload: {
+    blade: { id, name, title, param },
+    items: Record<string, unknown>[], // Always array of full objects
+    suggestions?: ISuggestion[],
+    locale?: string,
+  }
+}
+```
+
+### Agent -> Shell
+
+**PREVIEW_CHANGES** (form preview)
+
+```typescript
+{
+  type: "PREVIEW_CHANGES",
+  payload: {
+    data: Record<string, unknown>,
+    changedFields?: string[],
+  }
+}
+```
+
+**RELOAD_BLADE** (after save)
+
+```typescript
+{
+  type: "RELOAD_BLADE",
+  payload: { clearSelection?: boolean }
+}
+```
+
+**DOWNLOAD_FILE** (file download)
+
+```typescript
+{
+  type: "DOWNLOAD_FILE",
+  payload: {
+    filename: string,
+    contentType: string,
+    content: string // base64
+  }
+}
+```
+
+**NAVIGATE_TO_APP** (navigation)
+
+```typescript
+{
+  type: "NAVIGATE_TO_APP",
+  payload: { bladeName, param?, options? }
+}
+```
+
+## Architecture
+
+```
+Shell (VcApp)                          Agent (iframe)
+     │                                       │
+     │────── INIT_CONTEXT ─────────────────>│
+     │       (userId, locale, blade, items) │
+     │                                       │
+     │<───── CHAT_READY ────────────────────│
+     │                                       │
+     │────── UPDATE_CONTEXT ───────────────>│
+     │       (blade, items, suggestions)    │
+     │                                       │
+     │<───── PREVIEW_CHANGES ───────────────│
+     │       (updates form in shell)        │
+     │                                       │
+     │<───── RELOAD_BLADE ──────────────────│
+     │       (refreshes current blade)      │
+     │                                       │
+     │<───── DOWNLOAD_FILE ─────────────────│
+     │       (triggers file download)       │
+     └───────────────────────────────────────┘
+```
+
+## File Structure
+
+```
+framework/core/plugins/ai-agent/
+├── index.ts                    # Plugin entry point
+├── types.ts                    # TypeScript interfaces
+├── constants.ts                # Default values
+├── README.md                   # This file
+├── services/
+│   └── ai-agent-service.ts     # Panel state, postMessage
+├── composables/
+│   ├── index.ts
+│   ├── useAiAgent.ts           # Panel control
+│   └── useAiAgentContext.ts    # Data binding + preview
+└── components/
+    ├── index.ts
+    ├── VcAiAgentPanel.vue      # Main panel
+    └── _internal/
+        ├── VcAiAgentHeader.vue
+        └── VcAiAgentIframe.vue
+```

package/core/plugins/ai-agent/components/VcAiAgentPanel.vue

@@ -0,0 +1,125 @@
+<template>
+  <Transition name="ai-panel-slide">
+    <div
+      v-if="isOpen"
+      class="vc-ai-agent-panel"
+      :class="{
+        'vc-ai-agent-panel--expanded': isExpanded,
+      }"
+      :style="panelStyle"
+    >
+      <VcAiAgentHeader
+        :title="config.title"
+        :is-expanded="isExpanded"
+        :items-count="totalItemsCount"
+        @close="closePanel"
+        @expand="expandPanel"
+        @collapse="collapsePanel"
+      />
+
+      <div class="vc-ai-agent-panel__content">
+        <VcAiAgentIframe
+          :url="config.url"
+          @iframe-ready="onIframeReady"
+        />
+      </div>
+    </div>
+  </Transition>
+</template>
+
+<script lang="ts" setup>
+import { computed, onUnmounted, inject } from "vue";
+import { AiAgentServiceKey } from "../../../../injection-keys";
+import type { IAiAgentServiceInternal } from "../services/ai-agent-service";
+import VcAiAgentHeader from "./_internal/VcAiAgentHeader.vue";
+import VcAiAgentIframe from "./_internal/VcAiAgentIframe.vue";
+
+// Inject AI agent service
+const aiAgentService = inject(AiAgentServiceKey) as IAiAgentServiceInternal | undefined;
+
+if (!aiAgentService) {
+  console.error("[VcAiAgentPanel] AiAgentService not provided");
+}
+
+// Destructure service properties
+const config = computed(
+  () => aiAgentService?.config.value ?? { url: "", title: "AI Assistant", width: 360, expandedWidth: 500 },
+);
+const isOpen = computed(() => aiAgentService?.isOpen.value ?? false);
+const isExpanded = computed(() => aiAgentService?.isExpanded.value ?? false);
+const totalItemsCount = computed(() => aiAgentService?.totalItemsCount.value ?? 0);
+
+// Panel style with dynamic width
+const panelStyle = computed(() => ({
+  width: isExpanded.value ? "50%" : `${config.value.width ?? 350}px`,
+}));
+
+// Panel control methods
+const closePanel = () => aiAgentService?.closePanel();
+const expandPanel = () => aiAgentService?.expandPanel();
+const collapsePanel = () => aiAgentService?.collapsePanel();
+
+// Handle iframe ready event
+const onIframeReady = (iframe: HTMLIFrameElement) => {
+  aiAgentService?._setIframeRef(iframe);
+};
+
+// Clean up iframe ref on unmount
+onUnmounted(() => {
+  aiAgentService?._setIframeRef(null);
+});
+</script>
+
+<style lang="scss">
+:root {
+  --ai-panel-bg: var(--additional-50);
+  --ai-panel-border-color: var(--neutrals-200);
+  --ai-panel-shadow: -4px 0 12px rgba(0, 0, 0, 0.08);
+  --ai-panel-header-bg: var(--primary-50);
+  --ai-panel-header-border: var(--neutrals-200);
+  --ai-panel-icon-color: var(--primary-500);
+  --ai-panel-title-color: var(--secondary-950);
+  --ai-panel-badge-bg: var(--primary-100);
+  --ai-panel-badge-color: var(--primary-700);
+  --ai-panel-button-color: var(--neutrals-600);
+  --ai-panel-button-hover-bg: var(--neutrals-100);
+  --ai-panel-button-hover-color: var(--neutrals-900);
+  --ai-panel-iframe-bg: var(--additional-50);
+  --ai-panel-placeholder-bg: var(--neutrals-50);
+  --ai-panel-placeholder-icon-color: var(--neutrals-300);
+  --ai-panel-placeholder-text-color: var(--neutrals-500);
+}
+
+// Slide transition for panel
+.ai-panel-slide-enter-active,
+.ai-panel-slide-leave-active {
+  transition: transform var(--app-panel-transition-duration, 0.3s)
+    var(--app-panel-transition-timing, cubic-bezier(0.4, 0, 0.2, 1));
+}
+
+.ai-panel-slide-enter-from,
+.ai-panel-slide-leave-to {
+  transform: translateX(100%);
+}
+
+.vc-ai-agent-panel {
+  @apply tw-flex tw-flex-col tw-h-full tw-shrink-0;
+  background-color: var(--ai-panel-bg);
+  box-shadow: var(--ai-panel-shadow);
+  // Width transition for expand/collapse
+  transition: width var(--app-panel-transition-duration, 0.3s)
+    var(--app-panel-transition-timing, cubic-bezier(0.4, 0, 0.2, 1));
+  overflow: hidden;
+  border-width: 1px;
+  border-style: solid;
+  border-color: var(--ai-panel-border-color);
+
+  &--expanded {
+    // Additional expanded styles if needed
+  }
+
+  &__content {
+    @apply tw-flex-1 tw-overflow-hidden tw-flex tw-flex-col tw-pt-3;
+  }
+}
+</style>