@vc-shell/framework 1.0.327 → 1.0.328-0

package/core/plugins/modularity/README.md

@@ -0,0 +1,152 @@
+
+# Modularity Plugin
+
+The Modularity Plugin provides two main features:
+- Dynamic Module Loading
+- Extensions System
+
+## Dynamic Module Loading
+
+The Dynamic Module Loading system allows you to load Vue.js modules at runtime.
+
+### Usage
+
+
+```typescript
+import { useDynamicModules } from '@framework/core/plugins/modularity';
+import { createApp } from 'vue';
+import { createRouter } from 'vue-router';
+const app = createApp(App);
+const router = createRouter(/ router config /);
+const { load, extensionsHelper } = useDynamicModules(app, {
+    router,
+    appName: 'your-app-name'
+  }, 
+  {
+    baseUrl: 'https://your-modules-host.com/',
+    manifestFileName: 'manifest.json', // optional, default: 'manifest.json'
+  });
+// Load all modules
+await load();
+```
+
+### Module Structure
+
+Each module should have:
+1. A manifest file (manifest.json) describing module files generated by `Vite` during build time
+2. An entry point file that exports a Vue plugin
+3. Optional CSS files
+
+Example manifest.json:
+
+```json
+{
+  "entry": {
+  "file": "index.js",
+    "isEntry": true
+  },
+  "styles": {
+    "file": "styles.css"
+  }
+}
+```
+
+Example module:
+
+```typescript
+export default {
+  install(app, options) {
+  // Plugin installation code
+  },
+  extensions: {
+  // Optional extensions configuration
+  }
+}
+```
+
+## Extensions System
+
+The Extensions System enables communication between the application and its modules.
+
+### Types of Extensions
+
+1. **Inbound Extensions**: Extensions that allow the application to customize and extend the module's functionality
+2. **Outbound Extensions**: Extensions that the module provides to extend the application's functionality
+
+### Registering Extensions
+
+```typescript
+// In your module
+export default {
+  install(app) {
+  // Plugin installation code
+  },
+  extensions: {
+    inbound: {
+      'customization-point': {
+        // Extensions that this module accepts
+        someConfig: true
+      }
+    },
+    outbound: {
+      'extension-point': [
+        // Extensions this module provides
+        {
+          id: 'MyExtension',
+          component: MyComponent,
+        }
+      ]
+    }
+  }
+}
+```
+
+### Using Extensions Helper
+
+```typescript
+import { useExtensionsHelper } from '@vc-shell/framework';
+import { inject } from 'vue';
+
+// In your component setup
+const extensionsHelper = inject(extensionsHelperSymbol);
+// Get extensions provided by other modules
+const outboundExtensions = extensionsHelper.getOutboundExtensions('extension-point');
+// Get extensions configured for your module
+const inboundExtensions = extensionsHelper.getInboundExtensions('your-module-id', 'customization-point');
+// Get all extensions for a module
+const moduleExtensions = extensionsHelper.getModuleExtensions('your-module-id');
+```
+
+### Extension Types
+
+1. **Component Extensions**
+
+```typescript
+interface ExtensionPoint = {
+  id: string;
+  component: Component;
+}
+```
+
+2. **Composable Function Extensions**
+
+```typescript
+interface ComposableFunction = {
+  id: string;
+  fn: (...args: unknown[]) => unknown;
+}
+```
+
+3. **Configuration Object Extensions**
+
+```typescript
+type Extension = Record<string, unknown>;
+```
+
+## Best Practices
+
+1. Always provide unique IDs for extensions
+2. Document your module's extension points
+3. Handle missing or failed extensions gracefully
+4. Use TypeScript interfaces for type safety
+5. Keep extension configurations simple and serializable

package/core/plugins/modularity/extensions-helper.ts

@@ -0,0 +1,209 @@
+import { App, computed, ComputedRef, InjectionKey } from "vue";
+
+declare module "@vue/runtime-core" {
+  interface ComponentCustomProperties {
+    $extensions: ExtensionRegistry;
+  }
+}
+
+export interface ExtensionPoint {
+  id: string;
+  component: unknown;
+}
+
+export interface ComposableFunction {
+  id: string;
+  fn: (...args: unknown[]) => unknown;
+}
+
+export type Extension = Record<string, unknown>;
+
+export interface ExtensionRegistry {
+  inbound: {
+    [namespace: string]: {
+      [extensionPoint: string]: Extension;
+    };
+  };
+  outbound: {
+    [namespace: string]: {
+      [extensionPoint: string]: ExtensionPoint[] | ComposableFunction[] | Extension;
+    };
+  };
+}
+
+export interface ExtensionNamespace {
+  [point: string]: ExtensionPoint[] | ComposableFunction[] | Extension;
+}
+
+export interface ExtensionsHelper {
+  getInboundExtensions(namespace: string, point?: string): Extension;
+  getOutboundExtensions(point: string): (ExtensionPoint | ComposableFunction | Extension)[];
+  getModuleExtensions(namespace: string): {
+    inbound: Record<string, Extension>;
+    outbound: Record<string, ExtensionPoint[] | ComposableFunction[] | Extension>;
+  };
+  extensions: ComputedRef<ExtensionRegistry>;
+}
+
+export const extensionsHelperSymbol = Symbol("extensionsHelper") as InjectionKey<ExtensionsHelper>;
+
+export function createExtensionsHelper(app: App): ExtensionsHelper {
+  if (!app.config.globalProperties.$extensions) {
+    app.config.globalProperties.$extensions = {
+      inbound: {},
+      outbound: {},
+    } as ExtensionRegistry;
+  }
+
+  const helper: ExtensionsHelper = {
+    getInboundExtensions(namespace: string, point?: string) {
+      return point
+        ? app.config.globalProperties.$extensions.inbound[namespace][point]
+        : app.config.globalProperties.$extensions.inbound[namespace];
+    },
+
+    getOutboundExtensions(point: string) {
+      const result: (ExtensionPoint | ComposableFunction | Extension)[] = [];
+      Object.values(app.config.globalProperties.$extensions.outbound).forEach((namespace: unknown) => {
+        const typedNamespace = namespace as ExtensionNamespace;
+        if (typedNamespace[point]) {
+          const extension = typedNamespace[point];
+          if (Array.isArray(extension)) {
+            result.push(...extension);
+          } else if (
+            typeof extension === "object" &&
+            "id" in extension &&
+            "fn" in extension &&
+            typeof extension.fn === "function"
+          ) {
+            result.push(extension);
+          } else if (typeof extension === "object") {
+            result.push(extension as Extension);
+          }
+        }
+      });
+
+      return result;
+    },
+
+    getModuleExtensions(namespace: string) {
+      return {
+        inbound: app.config.globalProperties.$extensions.inbound[namespace] || {},
+        outbound: app.config.globalProperties.$extensions.outbound[namespace] || {},
+      };
+    },
+
+    extensions: computed(() => app.config.globalProperties.$extensions),
+  };
+
+  // Provide access to extensions through provide/inject
+  app.provide(extensionsHelperSymbol, helper);
+
+  // Provide direct access to extensions
+  app.provide("$extensions", app.config.globalProperties.$extensions);
+
+  return helper;
+}
+
+export function registerModuleExtensions(app: App, moduleId: string, extensions: ExtensionRegistry) {
+  if (!app.config.globalProperties.$extensions) {
+    app.config.globalProperties.$extensions = {
+      inbound: {},
+      outbound: {},
+    } as ExtensionRegistry;
+  }
+
+  const { inbound, outbound } = app.config.globalProperties.$extensions;
+
+  // Register inbound extensions
+  registerInboundExtensions(inbound, moduleId, extensions);
+
+  // Register outbound extensions
+  registerOutboundExtensions(outbound, moduleId, extensions);
+}
+
+function registerInboundExtensions(
+  inbound: ExtensionRegistry["inbound"],
+  moduleId: string,
+  extensions: ExtensionRegistry,
+) {
+  if (!inbound[moduleId]) {
+    inbound[moduleId] = {};
+  }
+
+  Object.entries(extensions.inbound || {}).forEach(([point, extension]) => {
+    if (typeof extension !== "object" || Array.isArray(extension)) {
+      console.warn(
+        `Invalid inbound extension type for point "${point}" in module "${moduleId}". Inbound extensions must be objects.`,
+      );
+      return;
+    }
+
+    inbound[moduleId][point] = {
+      ...(inbound[moduleId][point] || {}),
+      ...extension,
+    };
+  });
+}
+
+function registerOutboundExtensions(
+  outbound: ExtensionRegistry["outbound"],
+  moduleId: string,
+  extensions: ExtensionRegistry,
+) {
+  if (!outbound[moduleId]) {
+    outbound[moduleId] = {};
+  }
+
+  Object.entries(extensions.outbound || {}).forEach(([point, extension]) => {
+    initializeExtensionPoint(outbound[moduleId], point, extension);
+    mergeExtension(outbound[moduleId], point, extension);
+  });
+}
+
+function initializeExtensionPoint(
+  moduleOutbound: ExtensionRegistry["outbound"][string],
+  point: string,
+  extension: ExtensionPoint[] | ComposableFunction | Extension,
+) {
+  if (!moduleOutbound[point]) {
+    if (Array.isArray(extension)) {
+      moduleOutbound[point] = [];
+    } else if (typeof extension === "object" && "fn" in extension) {
+      moduleOutbound[point] = [];
+    } else if (typeof extension === "object") {
+      moduleOutbound[point] = {};
+    }
+  }
+}
+
+function isComposableFunction(value: unknown): value is ComposableFunction {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "id" in value &&
+    "fn" in value &&
+    typeof (value as ComposableFunction).fn === "function"
+  );
+}
+
+function mergeExtension(
+  moduleOutbound: ExtensionRegistry["outbound"][string],
+  point: string,
+  extension: ExtensionPoint[] | ComposableFunction | Extension,
+) {
+  if (Array.isArray(extension) && Array.isArray(moduleOutbound[point])) {
+    (moduleOutbound[point] as ExtensionPoint[]).push(...(extension as ExtensionPoint[]));
+  } else if (isComposableFunction(extension) && Array.isArray(moduleOutbound[point])) {
+    (moduleOutbound[point] as ComposableFunction[]).push(extension);
+  } else if (isObjectExtension(extension) && isObjectExtension(moduleOutbound[point])) {
+    moduleOutbound[point] = {
+      ...(moduleOutbound[point] as Extension),
+      ...extension,
+    };
+  }
+}
+
+function isObjectExtension(value: unknown): value is Extension {
+  return typeof value === "object" && !Array.isArray(value);
+}

package/core/plugins/modularity/index.ts

@@ -7,37 +7,39 @@ import { useMenuService, useNotifications } from "../../composables";
 import * as _ from "lodash-es";
 import { notification } from "../../../shared";
 
-export const createModule = (components: { [key: string]: BladeInstanceConstructor }, locales?: unknown) => ({
-  install(app: App): void {
-    // Register components
-    Object.entries(components).forEach(([componentName, component]) => {
-      // Check if the component is already registered
-      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(
-          `Component ${componentName} is already registered. It will be overwritten with the new component.`,
-        );
-      }
-      app.component(componentName, component);
-    });
-
-    // Load locales
-    if (locales) {
-      Object.entries(locales).forEach(([key, message]) => {
-        // Merge locale messages, overwriting existing ones
-        i18n.global.mergeLocaleMessage(key, message);
+export function createModule(components: { [key: string]: BladeInstanceConstructor }, locales?: unknown) {
+  return {
+    install(app: App): void {
+      // Register components
+      Object.entries(components).forEach(([componentName, component]) => {
+        // Check if the component is already registered
+        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(
+            `Component ${componentName} is already registered. It will be overwritten with the new component.`,
+          );
+        }
+        app.component(componentName, component);
       });
-    }
-  },
-});
 
-export const createAppModule = (
+      // Load locales
+      if (locales) {
+        Object.entries(locales).forEach(([key, message]) => {
+          // Merge locale messages, overwriting existing ones
+          i18n.global.mergeLocaleMessage(key, message);
+        });
+      }
+    },
+  };
+}
+
+export function createAppModule(
   pages: { [key: string]: BladeInstanceConstructor },
   locales?: { [key: string]: object },
   notificationTemplates?: { [key: string]: Component & { notifyType?: string } },
   moduleComponents?: { [key: string]: Component },
-) => {
+) {
   return {
     install(app: App, options?: { router: Router }): void {
       let routerInstance: Router;
@@ -245,6 +247,7 @@ export const createAppModule = (
       }
     },
   };
-};
+}
 
 export * from "./loader";
+export * from "./extensions-helper";

package/core/plugins/modularity/loader.ts

@@ -1,5 +1,6 @@
 import { App, Plugin } from "vue";
 import { Router } from "vue-router";
+import { ExtensionRegistry, createExtensionsHelper, registerModuleExtensions } from "./extensions-helper";
 
 interface ModuleManifest {
   file: string;
@@ -23,21 +24,54 @@ interface Apps {
   };
 }
 
-function loadCSS(url: string) {
-  return new Promise<void>((resolve, reject) => {
+interface ModuleWithDefaultExport {
+  default: {
+    install: Plugin;
+    extensions?: ExtensionRegistry;
+  };
+}
+
+interface ModuleWithNamedExport {
+  install: Plugin;
+  extensions?: ExtensionRegistry;
+}
+
+type ModuleExports = ModuleWithDefaultExport | ModuleWithNamedExport;
+
+function loadCSS(url: string): Promise<void> {
+  return new Promise((resolve, reject) => {
     const link = document.createElement("link");
     link.rel = "stylesheet";
     link.href = url;
     link.onload = () => resolve();
-    link.onerror = () => reject(new Error(`Failed to load CSS: ${url}`));
+    link.onerror = (e) => reject(new Error(`Failed to load CSS: ${url}, error: ${e}`));
     document.head.appendChild(link);
   });
 }
 
-export function useDynamicModules(app: App, { router, appName }: { router: Router; appName: string }) {
+interface ModuleConfig {
+  baseUrl: string;
+  manifestFileName: string;
+  entryPointKey: string;
+}
+
+const DEFAULT_CONFIG: Partial<ModuleConfig> = {
+  manifestFileName: "manifest.json",
+  entryPointKey: "isEntry",
+};
+
+export function useDynamicModules(
+  app: App,
+  { router, appName }: { router: Router; appName: string },
+  config: Partial<ModuleConfig> = {},
+) {
+  const finalConfig = { ...DEFAULT_CONFIG, ...config };
+  const loadedModules = new Set<string>();
+  const extensionsHelper = createExtensionsHelper(app);
+
   async function load() {
     try {
-      const appsUrl = "/Modules/$(VirtoCommerce.MarketplaceVendor)/Content/apps.json";
+      const appsUrl = finalConfig.baseUrl + "apps.json";
       const modules: Apps[] = await fetch(appsUrl).then((res) => res.json());
 
       const module = modules.find((module) => module[appName]);
@@ -48,68 +82,90 @@ export function useDynamicModules(app: App, { router, appName }: { router: Route
         if (!(appModules && appModules.length)) {
           throw new Error("Modules not found");
         }
+        const manifestPromises = appModules.map(async (module) => {
+          if (loadedModules.has(module.id)) {
+            return null;
+          }
 
-        for (const module of appModules) {
+          const moduleUrl = module.url.replace(/^([^/])/, "/$1").replace(/([^/])$/, "$1/");
           try {
-            const moduleUrl = module.url.replace(/^([^/])/, "/$1").replace(/([^/])$/, "$1/");
-            const manifestResponse = await fetch(moduleUrl + "manifest.json");
-
-            if (!manifestResponse.ok) {
-              console.error(`Failed to load manifest for module ${module.id}:`, manifestResponse.statusText);
-              continue;
+            const response = await fetch(moduleUrl + finalConfig.manifestFileName);
+            if (!response.ok) {
+              throw new Error(`Failed to load manifest for module '{ ${module.id} }': ${response.statusText}`);
             }
+            return {
+              moduleId: module.id,
+              moduleUrl,
+              manifest: (await response.json()) as Manifest,
+            };
+          } catch (error) {
+            console.error(error);
+            return null;
+          }
+        });
 
-            const manifest: Manifest = await manifestResponse.json();
+        const manifestResults = await Promise.all(manifestPromises);
+        const validManifests = manifestResults.filter(
+          (result): result is NonNullable<typeof result> => result !== null,
+        );
 
-            // Find entry point
+        for (const { moduleId, moduleUrl, manifest } of validManifests) {
+          try {
             const entry = Object.values(manifest).find((file) => (file as ModuleManifest).isEntry);
-
             if (!entry) {
-              console.error(`Entry file not found for module ${module.id}`);
-              continue;
+              throw new Error(`Entry file not found for module ${moduleId}`);
             }
 
-            // Load CSS files
-            await Promise.all(
-              Object.values(manifest)
-                .filter((file) => file.file.endsWith(".css"))
-                .map((file) => loadCSS(moduleUrl + `${file.file}`)),
-            ).catch((error) => {
-              console.error(`Failed to load styles for module ${module.id}:`, error);
-            });
+            const cssFiles = Object.values(manifest)
+              .filter((file) => file.file.endsWith(".css"))
+              .map((file) => loadCSS(moduleUrl + file.file));
 
-            // Load module
-            await import(/* @vite-ignore */ moduleUrl + entry.file).catch((error) => {
-              console.error(`Failed to load module ${module.id}:`, error);
-              return; // Skip to next module
+            await Promise.all(cssFiles).catch((error) => {
+              console.error(`Failed to load styles for module ${moduleId}:`, error);
             });
 
-            // Register plugins
-            Object.values(window.VcShellDynamicModules).forEach((mod) => {
-              try {
-                app.use((mod as Record<"default", Plugin>)?.default, { router });
-              } catch (error) {
-                console.error(`Failed to register plugin for module ${module.id}:`, error);
-              }
-            });
-
-            app.config.globalProperties.$dynamicModules = {
-              ...(app.config.globalProperties.$dynamicModules || {}),
-              ...window.VcShellDynamicModules,
-            };
-            app.provide("$dynamicModules", app.config.globalProperties.$dynamicModules);
+            await import(/* @vite-ignore */ moduleUrl + entry.file);
+
+            if (typeof window !== "undefined" && window.VcShellDynamicModules) {
+              Object.values(window.VcShellDynamicModules).forEach((mod) => {
+                try {
+                  const moduleExports = mod as ModuleExports;
+                  const moduleToInstall = "default" in moduleExports ? moduleExports.default : moduleExports;
+
+                  if ("install" in moduleToInstall) {
+                    app.use(moduleToInstall.install as Plugin, { router });
+
+                    if (moduleToInstall.extensions) {
+                      registerModuleExtensions(app, moduleId, moduleToInstall.extensions);
+                    }
+
+                    loadedModules.add(moduleId);
+                  } else {
+                    console.error(`Module ${moduleId} does not have an 'install' function`);
+                  }
+                } catch (error) {
+                  console.error(`Failed to register plugin for module ${moduleId}:`, error);
+                }
+              });
+            }
           } catch (error) {
-            console.error(`Failed to process module ${module.id}:`, error);
-            continue; // Skip to next module
+            console.error(`Failed to process module ${moduleId}:`, error);
           }
         }
       }
     } catch (error) {
       console.error("Failed to load modules:", error);
     }
+
+    app.config.globalProperties.$dynamicModules = {
+      ...(app.config.globalProperties.$dynamicModules || {}),
+      ...window.VcShellDynamicModules,
+    };
+    app.provide("$dynamicModules", app.config.globalProperties.$dynamicModules);
   }
 
   return {
     load,
+    extensionsHelper,
   };
 }