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

package/core/composables/index.ts

@@ -21,3 +21,5 @@ export * from "./useSettingsMenu";
 export * from "./useToolbar";
 export * from "./useDynamicProperties";
 export * from "./useBlade";
+// useBladeSelection and useAiAgent are now part of the ai-agent plugin
+// export * from "./core/plugins/ai-agent";

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

@@ -1,6 +1,12 @@
-import { Ref, computed, ref, ComputedRef } from "vue";
+import { computed, ref, ComputedRef } from "vue";
 import * as _ from "lodash-es";
 import { ICommonAsset } from "../../types";
+import { createLogger } from "../../utilities";
+
+const logger = createLogger("use-assets");
+
+/** Maximum number of concurrent uploads */
+const MAX_CONCURRENT_UPLOADS = 4;
 
 export interface IUseAssets {
   upload: (files: FileList, uploadPath: string, startingSortOrder?: number) => Promise<ICommonAsset[]>;
@@ -9,6 +15,60 @@ export interface IUseAssets {
   loading: ComputedRef<boolean>;
 }
 
+/**
+ * Uploads a single file and returns the asset
+ */
+async function uploadSingleFile(
+  file: File,
+  uploadPath: string,
+  index: number,
+  startingSortOrder?: number,
+): Promise<ICommonAsset | null> {
+  const formData = new FormData();
+  formData.append("file", file);
+
+  const result = await fetch(`/api/assets?folderUrl=/${uploadPath}`, {
+    method: "POST",
+    body: formData,
+  });
+
+  const response = await result.json();
+
+  if (response?.length) {
+    const uploadedFile = response[0];
+    uploadedFile.createdDate = new Date();
+    uploadedFile.sortOrder = startingSortOrder !== undefined && startingSortOrder >= 0 ? startingSortOrder + index + 1 : 0;
+    uploadedFile.url = uploadedFile.url ? decodeURI(uploadedFile.url) : "";
+
+    if ("size" in uploadedFile) {
+      uploadedFile.size = file.size;
+    }
+
+    return uploadedFile;
+  }
+
+  return null;
+}
+
+/**
+ * Processes items in batches with concurrency limit
+ */
+async function processBatched<T, R>(
+  items: T[],
+  processor: (item: T, index: number) => Promise<R>,
+  concurrency: number,
+): Promise<R[]> {
+  const results: R[] = [];
+
+  for (let i = 0; i < items.length; i += concurrency) {
+    const batch = items.slice(i, i + concurrency);
+    const batchResults = await Promise.all(batch.map((item, batchIndex) => processor(item, i + batchIndex)));
+    results.push(...batchResults);
+  }
+
+  return results;
+}
+
 export function useAssets(): IUseAssets {
   const loading = ref(false);
 
@@ -16,35 +76,19 @@ export function useAssets(): IUseAssets {
     try {
       loading.value = true;
 
-      const uploadedAssets: Ref<ICommonAsset[]> = ref([]);
-      for (let i = 0; i < files.length; i++) {
-        const formData = new FormData();
-        formData.append("file", files[i]);
-
-        const result = await fetch(`/api/assets?folderUrl=/${uploadPath}`, {
-          method: "POST",
-          body: formData,
-        });
-
-        const response = await result.json();
-
-        if (response?.length) {
-          const file = response[0];
-          file.createdDate = new Date();
-          file.sortOrder = startingSortOrder !== undefined && startingSortOrder >= 0 ? startingSortOrder + i + 1 : 0;
-          file.url = file.url ? decodeURI(file.url) : "";
+      const fileArray = Array.from(files);
 
-          if ("size" in file) {
-            file.size = files[i].size;
-          }
+      // Upload files in parallel batches
+      const uploadResults = await processBatched(
+        fileArray,
+        (file, index) => uploadSingleFile(file, uploadPath, index, startingSortOrder),
+        MAX_CONCURRENT_UPLOADS,
+      );
 
-          uploadedAssets.value.push(file);
-        }
-      }
-
-      return uploadedAssets.value;
+      // Filter out null results and return successful uploads
+      return uploadResults.filter((asset): asset is ICommonAsset => asset !== null);
     } catch (error) {
-      console.error(error);
+      logger.error("Upload failed:", error);
       throw error;
     } finally {
       loading.value = false;
@@ -63,7 +107,7 @@ export function useAssets(): IUseAssets {
 
       return updatedAssetArr;
     } catch (error) {
-      console.error(error);
+      logger.error("Remove failed:", error);
       throw error;
     } finally {
       loading.value = false;
@@ -71,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/useAsync/index.ts

@@ -1,6 +1,9 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { readonly, ref } from "vue";
 import { HasLoading } from "../useLoading";
+import { createLogger } from "../../utilities";
+
+const logger = createLogger("use-async");
 
 export type AsyncAction<Payload = void, Result = void> = (payload?: Payload, ...rest: any[]) => Promise<Result>;
 
@@ -18,7 +21,7 @@ export function useAsync<Payload = void, Result = void>(
     try {
       return await innerAction(payload, ...rest);
     } catch (e) {
-      console.error(e);
+      logger.error("Async action failed:", e);
       throw e;
     } finally {
       loading.value = false;

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();
+    });
+  });
+});