@vc-shell/framework 1.2.3-beta.1 → 1.2.4-beta.1

package/core/plugins/extension-points/ExtensionPoint.vue

@@ -0,0 +1,95 @@
+<template>
+  <!-- Scoped slot: host has full rendering control -->
+  <slot
+    v-if="$slots.default"
+    :components="visibleComponents"
+    :has-components="hasVisibleComponents"
+  />
+
+  <!-- Layout mode: wrapper with separator/gap -->
+  <div
+    v-else-if="hasLayout && hasVisibleComponents"
+    :class="wrapperClass"
+    :style="wrapperStyle"
+  >
+    <hr
+      v-if="separator"
+      :class="separatorClass || 'vc-extension-point__separator'"
+    >
+    <component
+      v-for="extension in visibleComponents"
+      :key="extension.id"
+      :is="extension.component"
+      v-bind="extension.props || {}"
+    />
+  </div>
+
+  <!-- Plain mode: no wrapper (backward-compatible) -->
+  <template v-else>
+    <component
+      v-for="extension in visibleComponents"
+      :key="extension.id"
+      :is="extension.component"
+      v-bind="extension.props || {}"
+    />
+  </template>
+</template>
+
+<script setup lang="ts">
+import { computed } from "vue";
+import { defineExtensionPoint } from "./defineExtensionPoint";
+import type { ExtensionComponent } from "./types";
+
+interface Props {
+  /** Extension point name (e.g. "auth:after-form") */
+  name: string;
+  /** Adds an <hr> separator before the components */
+  separator?: boolean;
+  /** Custom CSS class for the <hr> separator */
+  separatorClass?: string;
+  /** CSS class for the wrapper <div> */
+  wrapperClass?: string;
+  /** CSS gap value between components (e.g. "1rem", "16px") */
+  gap?: string;
+  /** Filter components by meta fields (e.g. { type: "action" }) */
+  filter?: Record<string, unknown>;
+}
+
+const props = defineProps<Props>();
+
+defineSlots<{
+  default?: (props: { components: ExtensionComponent[]; hasComponents: boolean }) => any;
+}>();
+
+// Auto-declares the extension point when the component is used in a template
+const { components } = defineExtensionPoint(props.name);
+
+const visibleComponents = computed(() => {
+  if (!props.filter) return components.value;
+  const entries = Object.entries(props.filter);
+  return components.value.filter(
+    (c) => c.meta && entries.every(([key, value]) => c.meta![key] === value),
+  );
+});
+
+const hasVisibleComponents = computed(() => visibleComponents.value.length > 0);
+
+const hasLayout = computed(
+  () => props.separator || props.separatorClass || props.wrapperClass || props.gap,
+);
+
+const wrapperStyle = computed(() => {
+  if (!props.gap) return undefined;
+  return {
+    display: "flex",
+    flexDirection: "column" as const,
+    gap: props.gap,
+  };
+});
+</script>
+
+<style lang="scss">
+.vc-extension-point__separator {
+  @apply tw-border-t tw-border-solid tw-border-[color:var(--secondary-200)] tw-mb-4;
+}
+</style>

package/core/plugins/extension-points/defineExtensionPoint.ts

@@ -0,0 +1,29 @@
+import { computed } from "vue";
+import { declarePoint, getPoint } from "./store";
+import type { ExtensionPointOptions, ExtensionComponent } from "./types";
+
+/**
+ * Declare an extension point (host-side).
+ *
+ * Used in pages/components that accept plugin content.
+ * Returns reactive computed refs for the registered components.
+ *
+ * @example
+ * ```ts
+ * const { hasComponents } = defineExtensionPoint("seller:commissions", {
+ *   description: "Commission fee fields in seller details form",
+ * });
+ * ```
+ */
+export function defineExtensionPoint(name: string, options: ExtensionPointOptions = {}) {
+  declarePoint(name, options);
+  const state = getPoint(name);
+
+  const components = computed<ExtensionComponent[]>(() =>
+    [...state.components].sort((a, b) => (a.priority || 0) - (b.priority || 0)),
+  );
+
+  const hasComponents = computed(() => state.components.length > 0);
+
+  return { components, hasComponents };
+}

package/core/plugins/extension-points/index.ts

@@ -1,8 +1,11 @@
-export {
-  useExtensionSlot,
-  useExtensionData,
-  useExtensions,
-  type ExtensionComponent,
-} from './simple-extensions';
+// Host-side: declare extension points in pages that accept plugins
+export { defineExtensionPoint } from "./defineExtensionPoint";
 
-export { default as ExtensionSlot } from './ExtensionSlot.vue';
+// Plugin-side: register components into extension points
+export { useExtensionPoint } from "./useExtensionPoint";
+
+// Render component
+export { default as ExtensionPoint } from "./ExtensionPoint.vue";
+
+// Types
+export type { ExtensionComponent, ExtensionPointOptions } from "./types";

package/core/plugins/extension-points/store.ts

@@ -0,0 +1,54 @@
+import { reactive } from "vue";
+import type { ExtensionPointState, ExtensionPointOptions } from "./types";
+
+const registry = reactive<Record<string, ExtensionPointState>>({});
+
+/**
+ * Declare an extension point (host-side).
+ * Safe to call multiple times — subsequent calls are no-ops with a dev warning.
+ * If a plugin already registered components before declaration, they are preserved.
+ */
+export function declarePoint(name: string, options: ExtensionPointOptions): void {
+  if (registry[name]?.declared) {
+    if (import.meta.env.DEV) {
+      console.warn(`[vc-shell] Extension point "${name}" is already declared.`);
+    }
+    return;
+  }
+
+  if (registry[name]) {
+    // Plugin registered before host declared — upgrade the entry
+    registry[name].declared = true;
+    registry[name].options = options;
+  } else {
+    registry[name] = { declared: true, options, components: [] };
+  }
+}
+
+/**
+ * Get reactive state for an extension point.
+ * Creates an undeclared entry if it doesn't exist (plugin registering before host).
+ * Warns in dev mode if the point was never declared.
+ */
+export function getPoint(name: string): ExtensionPointState {
+  if (!registry[name]) {
+    registry[name] = { declared: false, options: {}, components: [] };
+  }
+
+  if (import.meta.env.DEV && !registry[name].declared) {
+    const declared = Object.keys(registry).filter((k) => registry[k].declared);
+    console.warn(
+      `[vc-shell] Extension point "${name}" is not declared. ` +
+        `Available: ${declared.join(", ") || "(none)"}`,
+    );
+  }
+
+  return registry[name];
+}
+
+/**
+ * Get the full registry (for dev tools / testing).
+ */
+export function getRegistry(): Record<string, ExtensionPointState> {
+  return registry;
+}

package/core/plugins/extension-points/types.ts

@@ -0,0 +1,28 @@
+import type { Component } from "vue";
+
+export interface ExtensionComponent {
+  /** Unique identifier — used for replacement and removal */
+  id: string;
+  /** Vue component to render */
+  component: Component;
+  /** Props passed to the component via v-bind */
+  props?: Record<string, unknown>;
+  /** Sort order (lower = rendered first). Default: 0 */
+  priority?: number;
+  /** Arbitrary metadata for filtering (e.g. { type: "action" }) */
+  meta?: Record<string, unknown>;
+}
+
+export interface ExtensionPointOptions {
+  /** Human-readable description for dev tools and documentation */
+  description?: string;
+}
+
+export interface ExtensionPointState {
+  /** Whether a host has declared this point via defineExtensionPoint */
+  declared: boolean;
+  /** Options provided at declaration */
+  options: ExtensionPointOptions;
+  /** Registered components */
+  components: ExtensionComponent[];
+}

package/core/plugins/extension-points/useExtensionPoint.ts

@@ -0,0 +1,42 @@
+import { getPoint } from "./store";
+import type { ExtensionComponent } from "./types";
+
+/**
+ * Access an extension point (plugin-side).
+ *
+ * Used in module `install()` to register components into a host's extension point.
+ *
+ * @example
+ * ```ts
+ * const { add } = useExtensionPoint("auth:after-form");
+ * add({
+ *   id: "registration-button",
+ *   component: RegistrationButton,
+ *   props: { text: "Register" },
+ *   meta: { type: "action" },
+ * });
+ * ```
+ */
+export function useExtensionPoint(name: string) {
+  const state = getPoint(name);
+
+  /** Register or replace a component (matched by id). */
+  const add = (entry: ExtensionComponent): void => {
+    const idx = state.components.findIndex((c) => c.id === entry.id);
+    if (idx !== -1) {
+      state.components[idx] = entry;
+    } else {
+      state.components.push(entry);
+    }
+  };
+
+  /** Remove a component by id. */
+  const remove = (id: string): void => {
+    const idx = state.components.findIndex((c) => c.id === id);
+    if (idx !== -1) {
+      state.components.splice(idx, 1);
+    }
+  };
+
+  return { add, remove };
+}

package/core/plugins/modularity/index.ts

@@ -1,7 +1,7 @@
-import { App, Component, h, inject, resolveComponent, watch } from "vue";
+import { App, Component, inject, resolveComponent } from "vue";
 import { i18n } from "./../i18n";
 import { Router } from "vue-router";
-import { BladeInstanceConstructor, BladeVNode } from "./../../../shared/components/blade-navigation/types";
+import { BladeInstanceConstructor } from "./../../../shared/components/blade-navigation/types";
 import { kebabToPascal, createLogger } from "./../../utilities";
 import { addMenuItem, useMenuService, useNotifications } from "../../composables";
 import * as _ from "lodash-es";
@@ -37,20 +37,51 @@ export function createModule(components: { [key: string]: BladeInstanceConstruct
   };
 }
 
+/**
+ * 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 {
-      let routerInstance: Router;
-
       // 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 {
@@ -62,11 +93,6 @@ export function createAppModule(
         };
       }
 
-      if (options && options.router) {
-        const { router } = options;
-        routerInstance = router;
-      }
-
       const uid = _.uniqueId("module_");
 
       // Register pages
@@ -100,30 +126,11 @@ export function createAppModule(
             component: page,
             route: page.url,
             isWorkspace: page.isWorkspace || false,
+            routable: page.routable !== false,
           });
 
-          const mainRoute = routerInstance.getRoutes().find((r) => r.meta?.root);
-          if (!mainRoute) {
-            throw new Error("Main route not found. Make sure you have added `meta: {root: true}` to the main route.");
-          }
-          const mainRouteName = mainRoute.name;
-
-          const bladeVNodeForRouter = h(page, {
-            navigation: {},
-          }) as BladeVNode;
-
-          if (routerInstance.hasRoute(routeName)) {
-            routerInstance.removeRoute(routeName);
-          }
-
-          routerInstance.addRoute(mainRouteName as string, {
-            name: routeName,
-            path: page.url.substring(1),
-            components: { default: bladeVNodeForRouter },
-            meta: {
-              permissions: page.permissions,
-            },
-          });
+          // Note: No router.addRoute() — blades are NOT Vue Router pages.
+          // BladeStack manages blade rendering; Vue Router is URL sync only.
 
           if (page.menuItem) {
             addMenuItem({
@@ -182,6 +189,7 @@ export function createAppModule(
           if (app.component(name)) {
             // Overwrite existing component
             logger.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/services/_internal/createBladeScopedRegistry.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { createBladeScopedRegistry, type BladeScopedRegistry } from "./createBladeScopedRegistry";
+
+interface TestItem {
+  id: string;
+  bladeId?: string;
+  label?: string;
+}
+
+interface TestRegistration {
+  bladeId: string;
+  item: TestItem;
+}
+
+function createTestRegistry(): BladeScopedRegistry<TestItem, TestRegistration> {
+  return createBladeScopedRegistry<TestItem, TestRegistration>({
+    createRegistration: (bladeId, item) => ({ bladeId, item }),
+    getRegistrationBladeId: (r) => r.bladeId,
+    getRegistrationItemId: (r) => r.item.id,
+  });
+}
+
+describe("createBladeScopedRegistry", () => {
+  let registry: BladeScopedRegistry<TestItem, TestRegistration>;
+
+  beforeEach(() => {
+    registry = createTestRegistry();
+  });
+
+  it("registers and retrieves items by bladeId", () => {
+    registry.register({ id: "a", label: "A" }, "blade-1");
+    registry.register({ id: "b", label: "B" }, "blade-1");
+
+    const items = registry.get("blade-1");
+    expect(items).toHaveLength(2);
+    expect(items.map((i) => i.id)).toEqual(["a", "b"]);
+  });
+
+  it("normalizes bladeId to lowercase", () => {
+    registry.register({ id: "a" }, "Blade-1");
+    expect(registry.get("blade-1")).toHaveLength(1);
+    expect(registry.get("BLADE-1")).toHaveLength(1);
+  });
+
+  it("returns empty array for unknown bladeId", () => {
+    expect(registry.get("nonexistent")).toEqual([]);
+  });
+
+  it("returns defensive copy from get()", () => {
+    registry.register({ id: "a" }, "blade-1");
+    const copy = registry.get("blade-1");
+    copy.push({ id: "fake" });
+    expect(registry.get("blade-1")).toHaveLength(1);
+  });
+
+  it("upserts existing items instead of duplicating", () => {
+    registry.register({ id: "a", label: "original" }, "blade-1");
+    registry.register({ id: "a", label: "updated" }, "blade-1");
+
+    const items = registry.get("blade-1");
+    expect(items).toHaveLength(1);
+    expect(items[0].label).toBe("updated");
+  });
+
+  it("tracks registrations in the registrations array", () => {
+    registry.register({ id: "a" }, "blade-1");
+    registry.register({ id: "b" }, "blade-2");
+
+    expect(registry.registrations).toHaveLength(2);
+  });
+
+  it("unregister removes item and registration", () => {
+    registry.register({ id: "a" }, "blade-1");
+    registry.register({ id: "b" }, "blade-1");
+
+    registry.unregister("a", "blade-1");
+
+    expect(registry.get("blade-1")).toHaveLength(1);
+    expect(registry.get("blade-1")[0].id).toBe("b");
+    expect(registry.registrations).toHaveLength(1);
+  });
+
+  it("clear removes all items for a blade", () => {
+    registry.register({ id: "a" }, "blade-1");
+    registry.register({ id: "b" }, "blade-1");
+    registry.register({ id: "c" }, "blade-2");
+
+    registry.clear("blade-1");
+
+    expect(registry.get("blade-1")).toHaveLength(0);
+    expect(registry.get("blade-2")).toHaveLength(1);
+    expect(registry.registrations).toHaveLength(1);
+  });
+
+  it("update modifies an existing item in-place", () => {
+    registry.register({ id: "a", label: "original" }, "blade-1");
+    registry.update("a", "blade-1", { label: "modified" });
+
+    expect(registry.get("blade-1")[0].label).toBe("modified");
+  });
+
+  it("update is a no-op for non-existent item", () => {
+    registry.update("nonexistent", "blade-1", { label: "x" });
+    expect(registry.get("blade-1")).toHaveLength(0);
+  });
+
+  it("isRegistered tracks cross-blade registration count", () => {
+    registry.register({ id: "dup" }, "blade-a");
+    registry.register({ id: "dup" }, "blade-b");
+
+    expect(registry.isRegistered("dup")).toBe(true);
+
+    registry.unregister("dup", "blade-a");
+    expect(registry.isRegistered("dup")).toBe(true);
+
+    registry.unregister("dup", "blade-b");
+    expect(registry.isRegistered("dup")).toBe(false);
+  });
+
+  it("clear decrements registration counts", () => {
+    registry.register({ id: "a" }, "blade-1");
+    registry.register({ id: "a" }, "blade-2");
+
+    registry.clear("blade-1");
+    expect(registry.isRegistered("a")).toBe(true);
+
+    registry.clear("blade-2");
+    expect(registry.isRegistered("a")).toBe(false);
+  });
+});

package/core/services/_internal/createBladeScopedRegistry.ts

@@ -0,0 +1,127 @@
+import { reactive } from "vue";
+
+export interface BladeScopedRegistryOptions<TItem extends { id: string }, TRegistration> {
+  createRegistration: (bladeId: string, item: TItem) => TRegistration;
+  getRegistrationBladeId: (registration: TRegistration) => string;
+  getRegistrationItemId: (registration: TRegistration) => string;
+}
+
+export interface BladeScopedRegistry<TItem extends { id: string }, TRegistration> {
+  readonly registry: Record<string, TItem[]>;
+  readonly registrations: TRegistration[];
+  register(item: TItem, bladeId: string): void;
+  unregister(itemId: string, bladeId: string): void;
+  get(bladeId: string): TItem[];
+  clear(bladeId: string): void;
+  update(id: string, bladeId: string, partial: Partial<TItem>): void;
+  isRegistered(id: string): boolean;
+}
+
+export function createBladeScopedRegistry<TItem extends { id: string }, TRegistration>(
+  options: BladeScopedRegistryOptions<TItem, TRegistration>,
+): BladeScopedRegistry<TItem, TRegistration> {
+  const registry = reactive<Record<string, TItem[]>>({});
+  // Cast needed: reactive() unwraps refs in generics, but our TRegistration types are plain objects
+  const registrations = reactive([]) as TRegistration[];
+  const registrationCountById = reactive(new Map<string, number>());
+
+  function incrementCount(id: string): void {
+    registrationCountById.set(id, (registrationCountById.get(id) ?? 0) + 1);
+  }
+
+  function decrementCount(id: string): void {
+    const count = registrationCountById.get(id);
+    if (!count || count <= 1) {
+      registrationCountById.delete(id);
+      return;
+    }
+    registrationCountById.set(id, count - 1);
+  }
+
+  function register(item: TItem, bladeId: string): void {
+    const normalizedBladeId = bladeId.toLowerCase();
+
+    if (!registry[normalizedBladeId]) {
+      registry[normalizedBladeId] = [];
+    }
+
+    const existing = registry[normalizedBladeId].find((i) => i.id === item.id);
+    if (existing) {
+      Object.assign(existing, item, { bladeId: normalizedBladeId });
+      return;
+    }
+
+    const registryItem: TItem = { ...item, bladeId: normalizedBladeId } as TItem;
+    registry[normalizedBladeId].push(registryItem);
+    registrations.push(options.createRegistration(normalizedBladeId, registryItem));
+    incrementCount(item.id);
+  }
+
+  function unregister(itemId: string, bladeId: string): void {
+    const normalizedBladeId = bladeId.toLowerCase();
+
+    const bladeItems = registry[normalizedBladeId];
+    if (bladeItems) {
+      const itemIndex = bladeItems.findIndex((i) => i.id === itemId);
+      if (itemIndex !== -1) {
+        const [removedItem] = bladeItems.splice(itemIndex, 1);
+        if (removedItem) {
+          decrementCount(removedItem.id);
+        }
+      }
+    }
+
+    const registrationIndex = registrations.findIndex(
+      (r) => options.getRegistrationBladeId(r) === normalizedBladeId && options.getRegistrationItemId(r) === itemId,
+    );
+    if (registrationIndex !== -1) {
+      registrations.splice(registrationIndex, 1);
+    }
+  }
+
+  function get(bladeId: string): TItem[] {
+    const normalizedBladeId = bladeId ? bladeId.toLowerCase() : "";
+    return [...(registry[normalizedBladeId] || [])];
+  }
+
+  function clear(bladeId: string): void {
+    const normalizedBladeId = bladeId.toLowerCase();
+    const bladeItems = registry[normalizedBladeId];
+
+    if (bladeItems) {
+      bladeItems.forEach((item) => decrementCount(item.id));
+      delete registry[normalizedBladeId];
+    }
+
+    const registrationIndexes = registrations
+      .map((r, index) => (options.getRegistrationBladeId(r) === normalizedBladeId ? index : -1))
+      .filter((index) => index !== -1)
+      .reverse();
+
+    registrationIndexes.forEach((index) => {
+      registrations.splice(index, 1);
+    });
+  }
+
+  function update(id: string, bladeId: string, partial: Partial<TItem>): void {
+    const normalizedBladeId = bladeId.toLowerCase();
+    const existing = registry[normalizedBladeId]?.find((i) => i.id === id);
+    if (!existing) return;
+    Object.assign(existing, partial, { bladeId: normalizedBladeId });
+  }
+
+  function isRegistered(id: string): boolean {
+    return registrationCountById.has(id);
+  }
+
+  return {
+    registry,
+    registrations,
+    register,
+    unregister,
+    get,
+    clear,
+    update,
+    isRegistered,
+  };
+}