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

package/core/composables/useAppBarMobileButtons/index.ts

@@ -1,8 +1,16 @@
 import { inject, provide } from "vue";
 import { AppBarMobileButtonsServiceKey } from "../../../injection-keys";
 import { createAppBarMobileButtonsService } from "../../services/app-bar-mobile-buttons-service";
+import { createLogger, InjectionError } from "../../utilities";
+
+const logger = createLogger("use-app-bar-mobile-buttons");
 
 export function provideAppBarMobileButtonsService() {
+  const existingService = inject(AppBarMobileButtonsServiceKey, null);
+  if (existingService) {
+    return existingService;
+  }
+
   const service = createAppBarMobileButtonsService();
   provide(AppBarMobileButtonsServiceKey, service);
   return service;
@@ -11,7 +19,8 @@ export function provideAppBarMobileButtonsService() {
 export function useAppBarMobileButtons() {
   const service = inject(AppBarMobileButtonsServiceKey);
   if (!service) {
-    throw new Error("AppBarMobileButtonsService not found");
+    logger.error("AppBarMobileButtonsService not found");
+    throw new InjectionError("AppBarMobileButtonsService");
   }
   return service;
 }

package/core/composables/useAppBarWidget/index.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from "vitest";
+import { defineComponent, h, inject } from "vue";
+import { mount } from "@vue/test-utils";
+import { AppBarWidgetServiceKey } from "../../../injection-keys";
+import { provideAppBarWidget, useAppBarWidget } from "./index";
+import { createAppBarWidgetService } from "../../services/app-bar-menu-service";
+
+describe("useAppBarWidget", () => {
+  it("throws InjectionError when no service is provided", () => {
+    const TestComp = defineComponent({
+      setup() {
+        expect(() => useAppBarWidget()).toThrow("AppBarWidgetService");
+        return () => h("div");
+      },
+    });
+
+    mount(TestComp);
+  });
+
+  it("returns injected service", () => {
+    const service = createAppBarWidgetService();
+
+    const TestComp = defineComponent({
+      setup() {
+        const result = useAppBarWidget();
+        expect(result).toBe(service);
+        return () => h("div");
+      },
+    });
+
+    mount(TestComp, {
+      global: {
+        provide: { [AppBarWidgetServiceKey as symbol]: service },
+      },
+    });
+  });
+});
+
+describe("provideAppBarWidget", () => {
+  it("creates and provides a service", () => {
+    let providedService: any;
+    let injectedService: any;
+
+    const Parent = defineComponent({
+      setup() {
+        providedService = provideAppBarWidget();
+        return () => h(Child);
+      },
+    });
+
+    const Child = defineComponent({
+      setup() {
+        injectedService = inject(AppBarWidgetServiceKey);
+        return () => h("div");
+      },
+    });
+
+    mount(Parent);
+
+    expect(providedService).toBeDefined();
+    expect(injectedService).toBe(providedService);
+  });
+
+  it("is idempotent — returns existing service if already provided", () => {
+    let firstResult: any;
+    let secondResult: any;
+
+    const GrandParent = defineComponent({
+      setup() {
+        firstResult = provideAppBarWidget();
+        return () => h(Parent);
+      },
+    });
+
+    const Parent = defineComponent({
+      setup() {
+        secondResult = provideAppBarWidget();
+        return () => h("div");
+      },
+    });
+
+    mount(GrandParent);
+
+    expect(firstResult).toBe(secondResult);
+  });
+});

package/core/composables/useAppBarWidget/index.ts

@@ -1,17 +1,36 @@
-import { inject, provide } from "vue";
-import { addAppBarWidget, createAppBarWidgetService, IAppBarWidgetService } from "../../services/app-bar-menu-service";
+import { inject, provide, getCurrentScope, onScopeDispose } from "vue";
+import {
+  addAppBarWidget,
+  createAppBarWidgetService,
+  IAppBarWidgetService,
+  appBarWidgetBus,
+} from "../../services/app-bar-menu-service";
 import { AppBarWidgetServiceKey } from "../../../injection-keys";
+import { createLogger, InjectionError } from "../../utilities";
+
+const logger = createLogger("use-app-bar-widget");
 
 export function provideAppBarWidget(): IAppBarWidgetService {
+  const existingService = inject(AppBarWidgetServiceKey, null);
+  if (existingService) {
+    return existingService;
+  }
+
   const service = createAppBarWidgetService();
   provide(AppBarWidgetServiceKey, service);
+
+  if (getCurrentScope()) {
+    onScopeDispose(() => appBarWidgetBus.dispose(service));
+  }
+
   return service;
 }
 
 export function useAppBarWidget(): IAppBarWidgetService {
   const service = inject(AppBarWidgetServiceKey);
   if (!service) {
-    throw new Error("AppBarWidgetService not found");
+    logger.error("AppBarWidgetService not found");
+    throw new InjectionError("AppBarWidgetService");
   }
   return service;
 }

package/core/composables/useAssets/index.ts

@@ -115,6 +115,12 @@ export function useAssets(): IUseAssets {
   }
 
   function edit(updatedFiles: ICommonAsset[], initialAssetArr: ICommonAsset[]): ICommonAsset[] {
+    // When all items are passed (e.g. reorder), preserve the order of updatedFiles.
+    // When a subset is passed (e.g. single asset edit), update in place within initial order.
+    if (updatedFiles.length === initialAssetArr.length) {
+      return updatedFiles.map((file) => ({ ...file }));
+    }
+
     const updatedAssetArr = _.cloneDeep(initialAssetArr) || [];
 
     if (updatedAssetArr && updatedAssetArr.length) {

package/core/composables/useBlade/index.ts

@@ -1,9 +1,25 @@
-import { inject } from "vue";
+import { inject, computed } from "vue";
 import { BladeInstance } from "../../../injection-keys";
+import {
+    BladeDescriptorKey,
+    BladeStackKey,
+    BladeMessagingKey,
+} from "../../../shared/components/blade-navigation/types";
+import type {
+    BladeDescriptor,
+    BladeOpenEvent,
+    IBladeStack,
+    IBladeMessaging,
+} from "../../../shared/components/blade-navigation/types";
 
 /**
- * Composable for accessing the current blade instance
- * @returns The current blade instance
+ * Composable for accessing the current blade instance (legacy API).
+ *
+ * Returns a ComputedRef<IBladeInstance> — the same type as before.
+ * For the new extended API with actions (openBlade, closeSelf, etc.),
+ * use `useBladeContext()` instead.
+ *
+ * @returns The current blade instance (ComputedRef)
  */
 export function useBlade() {
     const blade = inject(BladeInstance);
@@ -13,3 +29,121 @@ export function useBlade() {
     }
     return blade;
 }
+
+/**
+ * Extended blade context composable (new API).
+ *
+ * Provides identity (id, param, options), actions (openBlade, closeSelf),
+ * communication (callParent, exposeToChildren), guards, and error management.
+ *
+ * Must be called inside a component rendered by VcBladeSlot (new render layer).
+ * Falls back gracefully when BladeDescriptor is not yet provided (old render layer).
+ *
+ * @example
+ * ```ts
+ * const { param, options, openBlade, closeSelf, callParent } = useBladeContext();
+ * openBlade({ name: "OrderDetails", param: orderId });
+ * const result = await callParent("reload");
+ * closeSelf();
+ * ```
+ */
+export function useBladeContext() {
+    const _descriptor = inject(BladeDescriptorKey);
+    const _bladeStack = inject(BladeStackKey);
+    const _messaging = inject(BladeMessagingKey);
+
+    if (!_descriptor || !_bladeStack || !_messaging) {
+        throw new Error(
+            "[useBladeContext] Missing required injections. " +
+            "Ensure the component is rendered inside VcBladeSlot (new render layer).",
+        );
+    }
+
+    // Assign to non-optional consts after the guard (TypeScript narrows)
+    const descriptor = _descriptor;
+    const bladeStack = _bladeStack;
+    const messaging = _messaging;
+
+    // ── Identity (read-only) ────────────────────────────────────────────────
+    const id = computed(() => descriptor.value.id);
+    const param = computed(() => descriptor.value.param);
+    const options = computed(() => descriptor.value.options);
+    const query = computed(() => descriptor.value.query);
+    const closable = computed(() => descriptor.value.parentId !== undefined);
+    const expanded = computed(() => {
+        const active = bladeStack.activeBlade.value;
+        return active?.id === descriptor.value.id;
+    });
+
+    // ── Actions ─────────────────────────────────────────────────────────────
+
+    async function openBlade(event: BladeOpenEvent): Promise<void> {
+        return bladeStack.openBlade({
+            ...event,
+            parentId: descriptor.value.id, // auto-set parent
+        });
+    }
+
+    async function closeSelf(): Promise<boolean> {
+        return bladeStack.closeBlade(descriptor.value.id);
+    }
+
+    async function replaceWith(event: BladeOpenEvent): Promise<void> {
+        return bladeStack.replaceCurrentBlade({
+            ...event,
+            parentId: descriptor.value.parentId,
+        });
+    }
+
+    // ── Communication ───────────────────────────────────────────────────────
+
+    async function callParent<T = unknown>(method: string, args?: unknown): Promise<T> {
+        return messaging.callParent<T>(descriptor.value.id, method, args);
+    }
+
+    function exposeToChildren(methods: Record<string, (...args: any[]) => any>): void {
+        messaging.exposeToChildren(descriptor.value.id, methods);
+    }
+
+    // ── Guards ───────────────────────────────────────────────────────────────
+
+    function onBeforeClose(guard: () => Promise<boolean>): void {
+        bladeStack.registerBeforeClose(descriptor.value.id, guard);
+    }
+
+    // ── Error management ────────────────────────────────────────────────────
+
+    function setError(error: unknown): void {
+        bladeStack.setBladeError(descriptor.value.id, error);
+    }
+
+    function clearError(): void {
+        bladeStack.clearBladeError(descriptor.value.id);
+    }
+
+    return {
+        // Identity
+        id,
+        param,
+        options,
+        query,
+        closable,
+        expanded,
+
+        // Actions
+        openBlade,
+        closeSelf,
+        replaceWith,
+
+        // Communication
+        callParent,
+        exposeToChildren,
+
+        // Guards
+        onBeforeClose,
+
+        // Error management
+        setError,
+        clearError,
+    };
+}

package/core/composables/useBladeRegistry/index.test.ts

@@ -0,0 +1,192 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createApp, defineComponent, h } from "vue";
+import { createBladeRegistry } from "./index";
+import type { IBladeRegistrationData } from "./index";
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+/** Minimal blade component mock satisfying isValidBladeComponent() */
+function makeBlade(name = "TestBlade") {
+  return defineComponent({ name, render: () => h("div") });
+}
+
+function makeRegistrationData(
+  overrides: Partial<IBladeRegistrationData> = {},
+): IBladeRegistrationData {
+  return {
+    component: makeBlade() as any,
+    ...overrides,
+  };
+}
+
+function createTestApp() {
+  return createApp({ render: () => h("div") });
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────────
+
+describe("createBladeRegistry", () => {
+  let app: ReturnType<typeof createApp>;
+
+  beforeEach(() => {
+    app = createTestApp();
+  });
+
+  // ── Basic registration ──────────────────────────────────────────────────
+
+  describe("registerBlade", () => {
+    it("registers a blade and makes it retrievable", () => {
+      const registry = createBladeRegistry(app);
+      const data = makeRegistrationData({ route: "/orders", isWorkspace: true });
+
+      registry._registerBladeFn("Orders", data);
+
+      expect(registry.getBlade("Orders")).toBe(data);
+      expect(registry.registeredBladesMap.value.has("Orders")).toBe(true);
+    });
+
+    it("registers component globally on the app", () => {
+      const registry = createBladeRegistry(app);
+      const blade = makeBlade("Orders");
+
+      registry._registerBladeFn("Orders", { component: blade as any, route: "/orders" });
+
+      expect(app.component("Orders")).toBe(blade);
+    });
+
+    it("throws on empty name", () => {
+      const registry = createBladeRegistry(app);
+      expect(() => registry._registerBladeFn("", makeRegistrationData())).toThrow(
+        "non-empty string",
+      );
+    });
+
+    it("throws when component is missing", () => {
+      const registry = createBladeRegistry(app);
+      expect(() =>
+        registry._registerBladeFn("Test", { component: undefined as any }),
+      ).toThrow("must include a component");
+    });
+  });
+
+  // ── P2.9: Duplicate registration (fail-fast) ────────────────────────────
+
+  describe("duplicate registration (P2.9)", () => {
+    it("throws on duplicate name by default", () => {
+      const registry = createBladeRegistry(app);
+      registry._registerBladeFn("Orders", makeRegistrationData({ route: "/orders" }));
+
+      expect(() =>
+        registry._registerBladeFn("Orders", makeRegistrationData({ route: "/orders" })),
+      ).toThrow("already registered");
+    });
+
+    it("allows overwrite when allowOverwrite=true", () => {
+      const registry = createBladeRegistry(app);
+      const first = makeRegistrationData({ route: "/orders" });
+      const second = makeRegistrationData({ route: "/orders-v2" });
+
+      registry._registerBladeFn("Orders", first);
+      registry._registerBladeFn("Orders", second, true);
+
+      expect(registry.getBlade("Orders")).toBe(second);
+    });
+
+    it("error message suggests allowOverwrite", () => {
+      const registry = createBladeRegistry(app);
+      registry._registerBladeFn("Orders", makeRegistrationData());
+
+      expect(() => registry._registerBladeFn("Orders", makeRegistrationData())).toThrow(
+        "allowOverwrite=true",
+      );
+    });
+  });
+
+  // ── P2.7: Reverse URL index (getBladeByRoute) ──────────────────────────
+
+  describe("getBladeByRoute (P2.7)", () => {
+    it("finds blade by route segment", () => {
+      const registry = createBladeRegistry(app);
+      const data = makeRegistrationData({ route: "/orders", isWorkspace: true });
+
+      registry._registerBladeFn("Orders", data);
+
+      const result = registry.getBladeByRoute("orders");
+      expect(result).toBeDefined();
+      expect(result!.name).toBe("Orders");
+      expect(result!.data).toBe(data);
+    });
+
+    it("finds blade with leading slash", () => {
+      const registry = createBladeRegistry(app);
+      registry._registerBladeFn("Orders", makeRegistrationData({ route: "/orders" }));
+
+      const result = registry.getBladeByRoute("/orders");
+      expect(result).toBeDefined();
+      expect(result!.name).toBe("Orders");
+    });
+
+    it("finds blade without leading slash", () => {
+      const registry = createBladeRegistry(app);
+      registry._registerBladeFn("Orders", makeRegistrationData({ route: "/orders" }));
+
+      const result = registry.getBladeByRoute("orders");
+      expect(result).toBeDefined();
+      expect(result!.name).toBe("Orders");
+    });
+
+    it("returns undefined for unknown route", () => {
+      const registry = createBladeRegistry(app);
+      registry._registerBladeFn("Orders", makeRegistrationData({ route: "/orders" }));
+
+      expect(registry.getBladeByRoute("/unknown")).toBeUndefined();
+    });
+
+    it("returns undefined for empty route", () => {
+      const registry = createBladeRegistry(app);
+      expect(registry.getBladeByRoute("")).toBeUndefined();
+    });
+
+    it("updates index on overwrite", () => {
+      const registry = createBladeRegistry(app);
+      registry._registerBladeFn("Orders", makeRegistrationData({ route: "/orders" }));
+      registry._registerBladeFn("OrdersV2", makeRegistrationData({ route: "/orders" }), false);
+
+      // Should fail because different name → duplicate route maps to last registered
+      // Actually "OrdersV2" is a different name so it won't fail on name check.
+      // The route index maps /orders → OrdersV2 (last registration wins)
+      const result = registry.getBladeByRoute("/orders");
+      expect(result!.name).toBe("OrdersV2");
+    });
+
+    it("handles blades without routes", () => {
+      const registry = createBladeRegistry(app);
+      registry._registerBladeFn("NoRoute", makeRegistrationData());
+
+      // No route, so reverse lookup shouldn't find it
+      expect(registry.getBladeByRoute("NoRoute")).toBeUndefined();
+    });
+  });
+
+  // ── getBladeComponent ──────────────────────────────────────────────────
+
+  describe("getBladeComponent", () => {
+    it("returns component from registry", () => {
+      const registry = createBladeRegistry(app);
+      const blade = makeBlade("Orders");
+      registry._registerBladeFn("Orders", { component: blade as any, route: "/orders" });
+
+      expect(registry.getBladeComponent("Orders")).toBe(blade);
+    });
+
+    it("returns undefined for unknown name", () => {
+      const registry = createBladeRegistry(app);
+      expect(registry.getBladeComponent("Unknown")).toBeUndefined();
+    });
+
+    it("returns undefined for empty name", () => {
+      const registry = createBladeRegistry(app);
+      expect(registry.getBladeComponent("")).toBeUndefined();
+    });
+  });
+});

package/core/composables/useBladeRegistry/index.ts

@@ -11,6 +11,7 @@ export interface IBladeRegistrationData {
   component: BladeInstanceConstructor;
   route?: string;
   isWorkspace?: boolean;
+  routable?: boolean;
   // ... other metadata
 }
 
@@ -29,13 +30,15 @@ export interface IBladeRegistry {
   getBlade: (name: string) => IBladeRegistrationData | undefined;
   /** Get blade component by name */
   getBladeComponent: (name: string) => BladeInstanceConstructor | undefined;
+  /** Reverse lookup: find blade name + data by URL route segment (O(1)) */
+  getBladeByRoute: (route: string) => { name: string; data: IBladeRegistrationData } | undefined;
 }
 
 /**
  * Extended interface for blade registry instance with internal registration function
  */
 export interface IBladeRegistryInstance extends IBladeRegistry {
-  _registerBladeFn: (name: string, registrationData: IBladeRegistrationData) => void;
+  _registerBladeFn: (name: string, registrationData: IBladeRegistrationData, allowOverwrite?: boolean) => void;
 }
 
 /**
@@ -61,13 +64,29 @@ function isValidBladeComponent(component: unknown): component is BladeInstanceCo
 export function createBladeRegistry(app: App): IBladeRegistryInstance {
   const registeredBladesInternal = shallowRef<Map<string, IBladeRegistrationData>>(new Map());
 
+  // Reverse index: normalized route → blade name (rebuilt on every registration)
+  const _routeIndex = new Map<string, string>();
+
+  function _normalizeRoute(route: string): string {
+    return route.startsWith("/") ? route : `/${route}`;
+  }
+
   /**
    * Registers a blade component in the registry
    *
    * @param name - Unique name for the blade
    * @param registrationData - Blade registration data including component and metadata
    */
-  function registerBlade(name: string, registrationData: IBladeRegistrationData): void {
+  /**
+   * Registers a blade component in the registry.
+   *
+   * @param name - Unique name for the blade
+   * @param registrationData - Blade registration data including component and metadata
+   * @param allowOverwrite - If true, allows overwriting an existing blade (default: false).
+   *   Use for dynamic module hot-reload scenarios only.
+   * @throws Error if blade name is already registered and allowOverwrite is false
+   */
+  function registerBlade(name: string, registrationData: IBladeRegistrationData, allowOverwrite = false): void {
     if (!name || typeof name !== "string") {
       throw new Error("BladeRegistry: Blade name must be a non-empty string");
     }
@@ -84,20 +103,36 @@ export function createBladeRegistry(app: App): IBladeRegistryInstance {
     const newMap = new Map(registeredBladesInternal.value);
 
     if (newMap.has(name)) {
-      logger.warn(`Blade '${name}' is already registered. It will be overwritten.`);
+      if (!allowOverwrite) {
+        throw new Error(
+          `BladeRegistry: Blade '${name}' is already registered. ` +
+            `Use allowOverwrite=true if intentional (e.g. dynamic module hot-reload).`,
+        );
+      }
+      logger.warn(`Blade '${name}' is already registered. Overwriting (allowOverwrite=true).`);
     }
 
     // Register component globally if not already registered or different
     const existingGlobalComponent = app.component(name);
     if (!existingGlobalComponent || existingGlobalComponent !== registrationData.component) {
       if (existingGlobalComponent && existingGlobalComponent !== registrationData.component) {
-        logger.warn(`Global component '${name}' already exists and is different. Overwriting with new blade component.`);
+        logger.warn(
+          `Global component '${name}' already exists and is different. Overwriting with new blade component.`,
+        );
+        logger.warn(
+          `Global component '${name}' already exists and is different. Overwriting with new blade component.`,
+        );
       }
       app.component(name, registrationData.component);
     }
 
     newMap.set(name, registrationData);
     registeredBladesInternal.value = newMap;
+
+    // Maintain reverse route index
+    if (registrationData.route) {
+      _routeIndex.set(_normalizeRoute(registrationData.route), name);
+    }
   }
 
   /**
@@ -139,11 +174,29 @@ export function createBladeRegistry(app: App): IBladeRegistryInstance {
       }
     } catch (error) {
       logger.warn(`Error accessing global component '${name}':`, error);
+      logger.warn(`Error accessing global component '${name}':`, error);
     }
 
     return undefined;
   }
 
+  /**
+   * Reverse lookup: find a blade by its URL route segment.
+   * Uses O(1) index maintained during registration.
+   *
+   * @param route - URL segment (e.g. "orders" or "/orders")
+   * @returns Blade name and registration data, or undefined if not found
+   */
+  function getBladeByRoute(route: string): { name: string; data: IBladeRegistrationData } | undefined {
+    if (!route) return undefined;
+    const normalized = _normalizeRoute(route);
+    const name = _routeIndex.get(normalized);
+    if (!name) return undefined;
+    const data = registeredBladesInternal.value.get(name);
+    if (!data) return undefined;
+    return { name, data };
+  }
+
   // Cache the readonly map to avoid recreating it on every access
   const readonlyBladesMap = computed(() => vueReadonly(registeredBladesInternal.value));
 
@@ -151,6 +204,7 @@ export function createBladeRegistry(app: App): IBladeRegistryInstance {
     registeredBladesMap: readonlyBladesMap,
     getBlade,
     getBladeComponent,
+    getBladeByRoute,
   };
 
   return {