@vc-shell/framework 1.2.4-beta.7 → 2.0.0-alpha.0

package/core/plugins/modularity/README.md

@@ -1,482 +0,0 @@
-# Modularity Plugin
-
-The Modularity Plugin provides three main features:
-- Dynamic Module Loading
-- Extensions System
-- Module Versioning and Compatibility
-
-## 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, getLoadedModulesWithVersions } = useDynamicModules(app, {
-    router,
-    appName: 'your-app-name'
-  }, 
-  {
-    baseUrl: 'https://your-modules-host.com/',
-    manifestFileName: 'manifest.json', // optional, default: 'manifest.json'
-    frameworkVersion: '1.2.3', // current framework version
-    appVersion: '2.0.0', // current application version
-    skipVersionCheck: process.env.NODE_ENV === 'development', // optional, skip version check in dev mode
-  });
-// Load all modules
-await load();
-
-// Get information about loaded modules with their versions
-const loadedModules = getLoadedModulesWithVersions();
-console.log(`Loaded modules: ${loadedModules.size}`);
-```
-
-### 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
-4. Optional version.json file with versioning information
-
-Example manifest.json:
-
-```json
-{
-  "src/modules/index.ts": {
-    "file": "index.js",
-    "name": "index",
-    "src": "src/modules/index.ts",
-    "isEntry": true
-  },
-  "style.css": {
-    "file": "style.css",
-    "src": "style.css"
-  },
-  "version.json": {
-    "file": "version.json",
-    "src": "version.json",
-    "isVersionInfo": true
-  }
-}
-```
-
-Example module:
-
-```typescript
-export default {
-  install(app, options) {
-    // Plugin installation code
-  },
-  extensions: {
-    // Optional extensions configuration
-  },
-  version: {
-    version: '1.0.0',
-    compatibleWith: {
-      framework: '^1.2.0', // Compatible with framework version 1.2.x
-      modules: {
-        'dependency-module': '>=2.0.0' // Requires dependency-module version 2.0.0 or higher
-      }
-    },
-    appCompatibility: {
-      'vendor-portal': '>=2.0.0', // Compatible with vendor-portal app version 2.0.0 or higher
-      'admin-app': '^1.0.0'       // Compatible with admin-app version 1.x.x
-    }
-  }
-}
-```
-
-## Module Versioning System
-
-The Module Versioning System ensures compatibility between:
-- Modules and the framework
-- Modules and specific applications
-- Modules and other modules
-
-### Version Information Structure
-
-```typescript
-interface VersionInfo {
-  version: string;
-  compatibleWith: {
-    framework: string; // Framework version range (semver)
-    modules?: Record<string, string>; // Dependencies on other modules
-  };
-  appCompatibility?: {
-    [appName: string]: string; // Compatible application names and version ranges
-  }
-}
-```
-
-### Setting Up Module Versioning
-
-There are three ways to specify version information:
-
-1. **In the module's code** (highest priority):
-
-```typescript
-export default {
-  install(app, options) { /* ... */ },
-  version: {
-    version: '1.0.0',
-    compatibleWith: {
-      framework: '^1.2.0'
-    },
-    appCompatibility: {
-      'vendor-portal': '>=2.0.0',
-      'admin-app': '^1.0.0'
-    }
-  }
-}
-```
-
-2. **Using a version.json file** (medium priority):
-
-```json
-{
-  "version": "1.0.0",
-  "compatibleWith": {
-    "framework": "^1.2.0",
-    "modules": {
-      "other-module": ">=1.0.0"
-    }
-  },
-  "appCompatibility": {
-    "vendor-portal": ">=2.0.0"
-  }
-}
-```
-
-3. **In the apps.json file** (lowest priority):
-
-```json
-[
-  {
-    "vendor-portal": {
-      "modules": [
-        {
-          "id": "my-module",
-          "url": "/modules/my-module/",
-          "version": "1.0.0"
-        }
-      ]
-    }
-  }
-]
-```
-
-### Version Patterns
-
-The versioning system uses [semver](https://semver.org/) syntax for version ranges:
-
-- `*` - Compatible with any version
-- `1.2.3` - Requires exact version 1.2.3
-- `^1.2.3` - Compatible with 1.2.3 up to but not including 2.0.0
-- `~1.2.3` - Compatible with 1.2.3 up to but not including 1.3.0
-- `>=1.2.3` - Version 1.2.3 or higher
-- `1.2.3 - 1.5.0` - Range between 1.2.3 and 1.5.0 (inclusive)
-
-### Application Compatibility
-
-To specify which applications your module is compatible with:
-
-```typescript
-appCompatibility: {
-  // Compatible with any version of vendor-portal
-  'vendor-portal': '*',
-  
-  // Compatible with admin-app version 2.0.0 and above
-  'admin-app': '>=2.0.0',
-  
-  // Compatible with any application (if appCompatibility is omitted entirely,
-  // the module is also considered compatible with any application)
-  '*': '*'
-}
-```
-
-If an application name is not listed in `appCompatibility`, the module will not be loaded in that application.
-
-### Setting Up Vite Config for Module Versioning
-
-Here's a complete example of a Vite configuration that supports the versioning system:
-
-```javascript
-import { defineConfig } from "vite";
-import { resolve, join, dirname } from "node:path";
-import vue from "@vitejs/plugin-vue";
-import { fileURLToPath } from "node:url";
-import fs from "node:fs";
-import pkg from "./package.json";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-// Get dependency versions from package.json
-const { version, dependencies = {}, peerDependencies = {} } = pkg;
-
-// Function to read framework version from dependencies
-const getFrameworkVersion = () => {
-  const frameworkDep = dependencies["@vc-shell/framework"] || 
-                      peerDependencies["@vc-shell/framework"] || 
-                      "^1.0.0";
-  return frameworkDep.replace(/^\^|~/, ""); // Remove ^ or ~ prefixes
-};
-
-export default defineConfig({
-  build: {
-    manifest: "manifest.json",
-    copyPublicDir: false,
-    sourcemap: true,
-    minify: false,
-    lib: {
-      entry: resolve(__dirname, "./index.ts"),
-      fileName: (format, name) => `${name}.js`,
-      formats: ["umd"],
-      name: "VcShellDynamicModules",
-    },
-    outDir: join(__dirname, "../../dist/packages/modules"),
-    rollupOptions: {
-      output: {
-        globals: {
-          vue: "Vue",
-          "vue-router": "VueRouter",
-          "vee-validate": "VeeValidate",
-          "vue-i18n": "VueI18n",
-          moment: "moment",
-          "lodash-es": "_",
-          "@vueuse/core": "VueUse",
-          "@vc-shell/framework": "VcShellFramework",
-        },
-        banner: () => {
-          const versionInfo = {
-            version,
-            compatibleWith: {
-              framework: peerDependencies["@vc-shell/framework"] || "^" + getFrameworkVersion(),
-              modules: {}
-            },
-            appCompatibility: {
-              "vendor-portal": ">=2.0.0",
-              "admin-app": "^1.0.0"
-            }
-          };
-          
-          return `
-            /* Module Version Info */
-            (function() {
-              if (typeof window !== 'undefined') {
-                window.__VC_SHELL_MODULE_VERSION_INFO__ = window.__VC_SHELL_MODULE_VERSION_INFO__ || {};
-                window.__VC_SHELL_MODULE_VERSION_INFO__["${pkg.name}"] = ${JSON.stringify(versionInfo)};
-              }
-            })();
-          `;
-        }
-      },
-      external: [
-        /node_modules/,
-        "@vc-shell/framework",
-        "vue",
-        "vue-router",
-        "vee-validate",
-        "vue-i18n",
-        "moment",
-        "lodash-es",
-        "@vueuse/core",
-      ],
-    },
-  },
-  plugins: [
-    vue(),
-    {
-      name: 'module-version-plugin',
-      apply: 'build',
-      enforce: 'post',
-      
-      // Modify manifest.json after it's created
-      closeBundle: async () => {
-        const manifestPath = join(__dirname, "../../dist/packages/modules/manifest.json");
-        
-        if (fs.existsSync(manifestPath)) {
-          try {
-            // Read generated manifest
-            const manifestContent = await fs.promises.readFile(manifestPath, 'utf-8');
-            const manifest = JSON.parse(manifestContent);
-            
-            // Add version metadata file
-            const versionFileName = 'version.json';
-            const versionFilePath = join(__dirname, "../../dist/packages/modules/", versionFileName);
-            
-            // Create version info
-            const versionInfo = {
-              version: pkg.version,
-              compatibleWith: {
-                framework: peerDependencies["@vc-shell/framework"] || "^" + getFrameworkVersion(),
-                modules: {}
-              },
-              appCompatibility: {
-                "vendor-portal": ">=2.0.0",
-                "admin-app": "^1.0.0"
-              }
-            };
-            
-            // Write version file
-            await fs.promises.writeFile(versionFilePath, JSON.stringify(versionInfo, null, 2));
-            
-            // Add version file info to manifest
-            manifest[versionFileName] = {
-              file: versionFileName,
-              src: versionFileName,
-              isVersionInfo: true // Special marker
-            };
-            
-            // Write updated manifest
-            await fs.promises.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
-            
-            console.log(`✓ Version information added to manifest: ${manifestPath}`);
-          } catch (error) {
-            console.error('Error updating manifest with version info:', error);
-          }
-        } else {
-          console.warn(`Manifest file not found at ${manifestPath}`);
-        }
-      }
-    }
-  ],
-});
-```
-
-### Accessing Version Information in the Module
-
-In your module code, you can access the version information:
-
-```typescript
-// In your module's index.ts
-import pkg from './package.json';
-
-export default {
-  install(app, options) {
-    // Your module code
-  },
-  // Access version info from window global if available (set by banner in vite config),
-  // or fall back to static configuration
-  version: window.__VC_SHELL_MODULE_VERSION_INFO__?.[pkg.name] || {
-    version: pkg.version,
-    compatibleWith: {
-      framework: "^1.0.0"
-    },
-    appCompatibility: {
-      "vendor-portal": ">=2.0.0"
-    }
-  }
-};
-```
-
-### Error Handling
-
-When a module fails the compatibility check, it won't be loaded, and an error message will be logged to the console:
-
-```
-Version compatibility error: Module my-module requires framework version ^2.0.0, but current is 1.2.3
-```
-
-or
-
-```
-Module my-module is not compatible with application customer-app. This module supports only: vendor-portal, admin-app
-```
-
-## 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 version information for your modules.
-2. Use semantic versioning for your module versions.
-3. Be explicit about framework compatibility requirements.
-4. Specify application compatibility if your module is designed for specific applications.
-5. Handle missing extensions gracefully.
-6. Test your modules with different versions of the framework and applications.
-7. Consider using the `skipVersionCheck` option in development for easier testing.
-8. Document your module's version compatibility requirements.
-9. Keep version.json and manifest.json files up to date when deploying modules.
-10. Use the error messages to troubleshoot version compatibility issues.

package/core/plugins/modularity/index.ts

@@ -1,208 +0,0 @@
-import { App, Component, inject, resolveComponent } from "vue";
-import { i18n } from "@core/plugins/i18n";
-import { Router } from "vue-router";
-import type { BladeInstanceConstructor } from "@shared/components/blade-navigation/types";
-import { kebabToPascal, createLogger } from "@core/utilities";
-import { addMenuItem, useMenuService } from "@core/composables/useMenuService";
-import { useNotifications } from "@core/composables/useNotifications";
-import * as _ from "lodash-es";
-import { notification } from "@shared/components/notifications/core";
-import { BladeRegistryKey, IBladeRegistrationData, IBladeRegistryInstance } from "@core/composables/useBladeRegistry";
-
-const logger = createLogger("modularity");
-
-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
-          logger.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);
-        });
-      }
-    },
-  };
-}
-
-/**
- * Options for createAppModule.
- */
-export interface AppModuleOptions {
-  /**
-   * List of blade names that must already be registered before this module installs.
-   * Used to enforce load-order dependencies between modules.
-   *
-   * @example
-   * ```ts
-   * export default createAppModule(pages, locales, undefined, undefined, {
-   *   dependsOn: ["SellerDetails", "Products"],
-   * });
-   * ```
-   */
-  dependsOn?: string[];
-}
-
-export function createAppModule(
-  pages: { [key: string]: BladeInstanceConstructor },
-  locales?: { [key: string]: object },
-  notificationTemplates?: { [key: string]: Component & { notifyType?: string } },
-  moduleComponents?: { [key: string]: Component },
-  moduleOptions?: AppModuleOptions,
-) {
-  return {
-    install(app: App, options?: { router: Router }): void {
-      // Inject the BladeRegistry instance
-      const bladeRegistry = app.runWithContext(() => inject<IBladeRegistryInstance>(BladeRegistryKey));
-      let registerBladeWithRegistry: (name: string, data: IBladeRegistrationData) => void;
-
-      // Validate module dependencies (must be registered before this module)
-      if (moduleOptions?.dependsOn?.length && bladeRegistry) {
-        const missing = moduleOptions.dependsOn.filter(
-          (dep) => !bladeRegistry.getBlade(dep),
-        );
-        if (missing.length > 0) {
-          const moduleName = Object.values(pages)[0]?.name || "unknown";
-          logger.error(
-            `Module '${moduleName}' depends on blades [${missing.join(", ")}] ` +
-            `which are not yet registered. Ensure dependent modules are installed first.`,
-          );
-        }
-      }
-
-      if (bladeRegistry && bladeRegistry._registerBladeFn) {
-        registerBladeWithRegistry = bladeRegistry._registerBladeFn;
-      } else {
-        logger.error(
-          "createAppModule: BladeRegistry or its _registerBladeFn not found via inject. Blade registration will be skipped.",
-        );
-        registerBladeWithRegistry = (name: string, data: IBladeRegistrationData) => {
-          logger.warn(`BladeRegistry (noop): Tried to register '${name}' but _registerBladeFn is missing.`);
-        };
-      }
-
-      const uid = _.uniqueId("module_");
-
-      // Register pages
-      Object.values(pages).forEach((page) => {
-        if (!("routable" in page)) {
-          page.routable = true;
-        }
-
-        // All components registered through this plugin are blades
-        page.isBlade = true;
-
-        if (!page.url) {
-          if (page.name) {
-            registerBladeWithRegistry(page.name, {
-              component: page,
-              isWorkspace: page.isWorkspace || false,
-            });
-          } else {
-            logger.warn(
-              "createAppModule: Page without URL is missing a name. Cannot register with BladeRegistry.",
-              page,
-            );
-          }
-        } else {
-          const routeName = page.name || kebabToPascal(page.url.substring(1));
-          if (page.name !== routeName) {
-            page.name = routeName;
-          }
-
-          registerBladeWithRegistry(routeName, {
-            component: page,
-            route: page.url,
-            isWorkspace: page.isWorkspace || false,
-            routable: page.routable !== false,
-          });
-
-          // Note: No router.addRoute() — blades are NOT Vue Router pages.
-          // BladeStack manages blade rendering; Vue Router is URL sync only.
-
-          if (page.menuItem) {
-            addMenuItem({
-              ...page.menuItem,
-              icon: resolveComponent(page.menuItem.icon as string),
-              url: page.url,
-              routeId: routeName,
-              permissions: page.permissions || page.menuItem.permissions,
-            });
-          }
-        }
-
-        if (!page.moduleUid) {
-          page.moduleUid = uid;
-        }
-
-        if (page.notifyType) {
-          const notifyTypes = Array.isArray(page.notifyType) ? page.notifyType : [page.notifyType];
-
-          if (notifyTypes.length > 0) {
-            const { markAsRead, setNotificationHandler } = useNotifications(notifyTypes);
-
-            setNotificationHandler((message) => {
-              if (message.title) {
-                notification(message.title, {
-                  onClose() {
-                    markAsRead(message);
-                  },
-                });
-              }
-            });
-          }
-        }
-      });
-
-      if (notificationTemplates) {
-        // Register notification templates
-        Object.entries(notificationTemplates).forEach(([, template]) => {
-          // Remove existing template if it exists
-          if (app.config.globalProperties.notificationTemplates) {
-            const existingIndex = app.config.globalProperties.notificationTemplates.findIndex(
-              (t: Component & { notifyType: string }) => t.notifyType === template.notifyType,
-            );
-            if (existingIndex !== -1) {
-              app.config.globalProperties.notificationTemplates.splice(existingIndex, 1);
-            }
-          }
-          app.config.globalProperties.notificationTemplates?.push(template);
-        });
-      }
-
-      if (moduleComponents) {
-        // Register module components globally
-        Object.entries(moduleComponents).forEach(([name, component]) => {
-          // Check if the component is already registered
-          if (app.component(name)) {
-            // Overwrite existing component
-            logger.warn(`Component ${name} is already registered. It will be overwritten with the new component.`);
-          }
-          app.component(name, component);
-        });
-      }
-
-      if (locales) {
-        Object.entries(locales).forEach(([key, message]) => {
-          // Merge locale messages, overwriting existing ones
-          i18n.global.mergeLocaleMessage(key, message);
-        });
-      }
-    },
-  };
-}
-
-export * from "@core/plugins/modularity/loader";