@vc-shell/framework 1.2.4-beta.2 → 1.2.4-beta.3

package/ui/components/organisms/vc-app/composables/useShellBootstrap.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { ref, effectScope } from "vue";
+
+// ── Mocks for all service providers ────────────────────────────────
+const mockRegisterWidget = vi.fn();
+const mockRegisterMobileButton = vi.fn();
+const mockRegisterSettingsMenuItem = vi.fn();
+const mockProvide = vi.fn();
+const mockProvideAiAgentService = vi.fn();
+
+vi.mock("vue", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("vue")>();
+  return {
+    ...actual,
+    provide: (...args: unknown[]) => mockProvide(...args),
+    inject: (key: unknown) => {
+      if (key === AppBarWidgetServiceKey) return { register: mockRegisterWidget };
+      if (key === SettingsMenuServiceKey) return { register: mockRegisterSettingsMenuItem };
+      return undefined;
+    },
+    onScopeDispose: actual.onScopeDispose,
+  };
+});
+
+vi.mock("../../../../../core/composables/useAppBarMobileButtons", () => ({
+  provideAppBarMobileButtonsService: () => ({ register: mockRegisterMobileButton }),
+}));
+
+vi.mock("../../../../../core/composables/useGlobalSearch", () => ({
+  provideGlobalSearch: vi.fn(),
+}));
+
+vi.mock("../../../../../core/composables/useDashboard", () => ({
+  provideDashboardService: vi.fn(),
+}));
+
+vi.mock("../../../../../core/composables/useNotifications", () => ({
+  hasUnreadNotifications: ref(false),
+}));
+
+vi.mock("../../../../../shared/components", () => ({
+  NotificationDropdown: { template: "<div />" },
+}));
+
+vi.mock("../../../../../shared/components/language-selector", () => ({
+  LanguageSelector: { template: "<div />" },
+}));
+
+vi.mock("../../../../../shared/components/theme-selector", () => ({
+  ThemeSelector: { template: "<div />" },
+}));
+
+vi.mock("../../../../../shared/components/change-password-button", () => ({
+  ChangePasswordButton: { template: "<div />" },
+}));
+
+vi.mock("../../../../../shared/components/logout-button", () => ({
+  LogoutButton: { template: "<div />" },
+}));
+
+vi.mock("../../../../../core/plugins/ai-agent", () => ({
+  provideAiAgentService: (...args: unknown[]) => mockProvideAiAgentService(...args),
+}));
+
+// ── Import after mocks ─────────────────────────────────────────────
+import { useShellBootstrap, type ShellBootstrapOptions } from "@ui/components/organisms/vc-app/composables/useShellBootstrap";
+import {
+  AppBarWidgetServiceKey,
+  SettingsMenuServiceKey,
+  EmbeddedModeKey,
+  DynamicModulesKey,
+  ShellIndicatorsKey,
+  InternalRoutesKey,
+} from "@framework/injection-keys";
+import { hasUnreadNotifications } from "@core/composables/useNotifications";
+
+// ── Helpers ─────────────────────────────────────────────────────────
+function createOptions(overrides: Partial<ShellBootstrapOptions> = {}): ShellBootstrapOptions {
+  return {
+    isEmbedded: false,
+    ...overrides,
+  };
+}
+
+function bootstrapInScope(options: ShellBootstrapOptions) {
+  const scope = effectScope();
+  scope.run(() => useShellBootstrap(options));
+  return scope;
+}
+
+// ── Tests ───────────────────────────────────────────────────────────
+describe("useShellBootstrap", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    (hasUnreadNotifications as unknown as { value: boolean }).value = false;
+  });
+
+  describe("default notifications widget", () => {
+    it("registers notification-dropdown to app-bar", () => {
+      bootstrapInScope(createOptions());
+
+      expect(mockRegisterWidget).toHaveBeenCalledWith(
+        expect.objectContaining({ id: "notification-dropdown", icon: "lucide-bell", order: 10 }),
+      );
+    });
+
+    it("registers notification-dropdown to mobile-topbar when not embedded", () => {
+      bootstrapInScope(createOptions({ isEmbedded: false }));
+
+      expect(mockRegisterMobileButton).toHaveBeenCalledWith(
+        expect.objectContaining({ id: "notification-dropdown", isVisible: true }),
+      );
+    });
+
+    it("does NOT register mobile button when embedded", () => {
+      bootstrapInScope(createOptions({ isEmbedded: true }));
+
+      expect(mockRegisterMobileButton).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("default settings menu items", () => {
+    it("registers 4 default settings items", () => {
+      bootstrapInScope(createOptions());
+
+      expect(mockRegisterSettingsMenuItem).toHaveBeenCalledTimes(4);
+      const ids = mockRegisterSettingsMenuItem.mock.calls.map((c: unknown[]) => (c[0] as { id: string }).id);
+      expect(ids).toEqual(["theme-selector", "language-selector", "change-password", "logout"]);
+    });
+
+    it("registers items with correct groups", () => {
+      bootstrapInScope(createOptions());
+
+      expect(mockRegisterSettingsMenuItem).toHaveBeenCalledWith(
+        expect.objectContaining({ id: "theme-selector", group: "preferences" }),
+      );
+      expect(mockRegisterSettingsMenuItem).toHaveBeenCalledWith(
+        expect.objectContaining({ id: "logout", group: "account", order: 100 }),
+      );
+    });
+  });
+
+  describe("indicator state (ShellIndicatorsKey)", () => {
+    it("provides false when no unread notifications", () => {
+      bootstrapInScope(createOptions());
+
+      const provideCall = mockProvide.mock.calls.find(
+        ([key]: [unknown]) => key === ShellIndicatorsKey,
+      );
+      expect(provideCall).toBeDefined();
+      expect(provideCall![1].value).toBe(false);
+    });
+
+    it("reacts to hasUnreadNotifications changes", () => {
+      bootstrapInScope(createOptions());
+
+      const provideCall = mockProvide.mock.calls.find(
+        ([key]: [unknown]) => key === ShellIndicatorsKey,
+      );
+      expect(provideCall![1].value).toBe(false);
+
+      (hasUnreadNotifications as unknown as { value: boolean }).value = true;
+      expect(provideCall![1].value).toBe(true);
+    });
+  });
+
+  describe("ai-agent", () => {
+    it("does NOT provide AI agent service when no config", () => {
+      bootstrapInScope(createOptions());
+
+      expect(mockProvideAiAgentService).not.toHaveBeenCalled();
+    });
+
+    it("provides AI agent service when aiAgentConfig has url", () => {
+      bootstrapInScope(
+        createOptions({
+          aiAgentConfig: { url: "https://ai.example.com" } as any,
+          aiAgentAddGlobalToolbarButton: false,
+        }),
+      );
+
+      expect(mockProvideAiAgentService).toHaveBeenCalledWith({
+        config: expect.objectContaining({ url: "https://ai.example.com" }),
+        addGlobalToolbarButton: false,
+      });
+    });
+
+    it("defaults addGlobalToolbarButton to true", () => {
+      bootstrapInScope(
+        createOptions({
+          aiAgentConfig: { url: "https://ai.example.com" } as any,
+        }),
+      );
+
+      expect(mockProvideAiAgentService).toHaveBeenCalledWith(
+        expect.objectContaining({ addGlobalToolbarButton: true }),
+      );
+    });
+  });
+
+  describe("injection keys", () => {
+    it("provides EmbeddedModeKey", () => {
+      bootstrapInScope(createOptions({ isEmbedded: true }));
+
+      expect(mockProvide).toHaveBeenCalledWith(EmbeddedModeKey, true);
+    });
+
+    it("provides DynamicModulesKey when dynamicModules is defined", () => {
+      const modules = { testModule: {} };
+      bootstrapInScope(
+        createOptions({ dynamicModules: modules as unknown as typeof window.VcShellDynamicModules }),
+      );
+
+      expect(mockProvide).toHaveBeenCalledWith(DynamicModulesKey, modules);
+    });
+
+    it("does not provide DynamicModulesKey when dynamicModules is undefined", () => {
+      bootstrapInScope(createOptions());
+
+      const dynamicModulesCall = mockProvide.mock.calls.find(
+        ([key]: [unknown]) => key === DynamicModulesKey,
+      );
+      expect(dynamicModulesCall).toBeUndefined();
+    });
+
+    it("provides internalRoutes when specified", () => {
+      const routes = [{ path: "/test", component: {} }] as unknown as ShellBootstrapOptions["internalRoutes"];
+      bootstrapInScope(createOptions({ internalRoutes: routes }));
+
+      expect(mockProvide).toHaveBeenCalledWith(InternalRoutesKey, routes);
+    });
+  });
+});

package/ui/components/organisms/vc-app/composables/useShellBootstrap.ts

@@ -1,15 +1,27 @@
-import { computed, provide } from "vue";
-import { provideAppBarWidget, useNotifications } from "../../../../../core/composables";
-import { provideAppBarMobileButtonsService } from "../../../../../core/composables/useAppBarMobileButtons";
-import { provideSettingsMenu } from "../../../../../core/composables/useSettingsMenu";
-import { provideMenuService } from "../../../../../core/composables/useMenuService";
-import { provideGlobalSearch } from "../../../../../core/composables/useGlobalSearch";
-import { provideDashboardService } from "../../../../../core/composables/useDashboard";
-import { provideAiAgentService } from "../../../../../core/plugins/ai-agent";
-import type { IAiAgentConfig } from "../../../../../core/plugins/ai-agent";
-import { EMBEDDED_MODE, DynamicModulesKey } from "../../../../../injection-keys";
-import type { ShellFeature, ShellContext } from "../../../../../core/types/shell-feature";
-import type { BladeRoutesRecord } from "../../../../../shared/components";
+import { provide, inject, computed } from "vue";
+import { provideAppBarMobileButtonsService } from "@core/composables/useAppBarMobileButtons";
+import { provideGlobalSearch } from "@core/composables/useGlobalSearch";
+import { provideDashboardService } from "@core/composables/useDashboard";
+import {
+  AppBarWidgetServiceKey,
+  SettingsMenuServiceKey,
+  EmbeddedModeKey,
+  DynamicModulesKey,
+  ShellIndicatorsKey,
+  InternalRoutesKey,
+} from "@framework/injection-keys";
+import { hasUnreadNotifications } from "@core/composables/useNotifications";
+import { NotificationDropdown } from "@shared/components";
+import { LanguageSelector } from "@shared/components/language-selector";
+import { ThemeSelector } from "@shared/components/theme-selector";
+import { ChangePasswordButton } from "@shared/components/change-password-button";
+import { LogoutButton } from "@shared/components/logout-button";
+import { provideAiAgentService } from "@core/plugins/ai-agent";
+import type { IAiAgentConfig } from "@core/plugins/ai-agent";
+import type { BladeRoutesRecord } from "@shared/components";
+import type { registerAppBarWidgetOptions } from "@core/services/app-bar-menu-service";
+import type { AppBarButtonContent } from "@core/services/app-bar-mobile-buttons-service";
+import type { RegisterSettingsMenuItemOptions } from "@core/services/settings-menu-service";
 
 export interface ShellBootstrapOptions {
   isEmbedded: boolean;
@@ -17,62 +29,28 @@ export interface ShellBootstrapOptions {
   dynamicModules?: typeof window.VcShellDynamicModules;
   aiAgentConfig?: IAiAgentConfig;
   aiAgentAddGlobalToolbarButton?: boolean;
-  context: ShellContext;
 }
 
-/**
- * Bootstraps the shell: provides all core services and processes shell features.
- * This replaces the ~100 lines of service provisioning and registration
- * that were previously inline in vc-app.vue setup.
- */
-export function useShellBootstrap(features: ShellFeature[], options: ShellBootstrapOptions) {
-  // 1. Provide core services
-  const { register: registerSettingsMenuItem } = provideSettingsMenu();
-  const { register: registerWidget } = provideAppBarWidget();
-  const { register: registerMobileButton } = provideAppBarMobileButtonsService();
-  const { notifications } = useNotifications();
-  provideMenuService();
-  provideGlobalSearch();
-  provideDashboardService();
-
-  const hasUnreadNotifications = computed(() => notifications.value.some((item) => item.isNew));
+export function useShellBootstrap(options: ShellBootstrapOptions) {
+  // 1a. App-level services (created by framework plugin install)
+  const appBarWidgetService = inject(AppBarWidgetServiceKey)!;
+  const settingsMenuService = inject(SettingsMenuServiceKey)!;
+
+  // 1b. Component-scoped services (created here for VcApp descendants)
+  const mobileButtons = provideAppBarMobileButtonsService();
+  provideGlobalSearch();
+  provideDashboardService();
 
   // 2. Provide injection keys
-  provide(EMBEDDED_MODE, options.isEmbedded);
+  provide(EmbeddedModeKey, options.isEmbedded);
   if (options.internalRoutes) {
-    provide("internalRoutes", options.internalRoutes);
+    provide(InternalRoutesKey, options.internalRoutes);
   }
   if (options.dynamicModules !== undefined) {
     provide(DynamicModulesKey, options.dynamicModules);
   }
 
-  // 3. Process features — register their widgets/items/buttons into services
-  for (const feature of features) {
-    feature.appBarWidgets?.forEach((widget) => {
-      // Keep legacy notification behavior: badge reflects unread notifications.
-      if (widget.id === "notification-dropdown" && widget.badge === undefined) {
-        registerWidget({
-          ...widget,
-          badge: () => hasUnreadNotifications.value,
-        });
-        return;
-      }
-
-      registerWidget(widget);
-    });
-
-    feature.settingsMenuItems?.forEach((item) => registerSettingsMenuItem(item));
-
-    feature.mobileButtons?.forEach((button) => {
-      registerMobileButton({
-        ...button,
-        // Embedded mode hides all mobile buttons by default
-        isVisible: options.isEmbedded ? false : (button.isVisible ?? true),
-      });
-    });
-  }
-
-  // 4. Conditional AI agent setup
+  // 3. AI agent (conditional)
   if (options.aiAgentConfig?.url) {
     provideAiAgentService({
       config: options.aiAgentConfig,
@@ -80,8 +58,49 @@ export function useShellBootstrap(features: ShellFeature[], options: ShellBootst
     });
   }
 
-  // 5. Run feature onSetup hooks
-  for (const feature of features) {
-    feature.onSetup?.(options.context);
+  // 4. Register default shell UI
+  useShellDefaults({
+    isEmbedded: options.isEmbedded,
+    registerWidget: appBarWidgetService.register,
+    registerMobileButton: mobileButtons.register,
+    registerSettingsMenuItem: settingsMenuService.register,
+  });
+}
+
+// ── Internal: default UI element registration ─────────────────────
+interface ShellDefaultsContext {
+  isEmbedded: boolean;
+  registerWidget: (options: registerAppBarWidgetOptions) => string;
+  registerMobileButton: (button: AppBarButtonContent) => void;
+  registerSettingsMenuItem: (options: RegisterSettingsMenuItemOptions) => string;
+}
+
+function useShellDefaults(ctx: ShellDefaultsContext) {
+  // Notification widget
+  ctx.registerWidget({
+    id: "notification-dropdown",
+    component: NotificationDropdown,
+    icon: "lucide-bell",
+    order: 10,
+    badge: () => hasUnreadNotifications.value,
+  });
+
+  if (!ctx.isEmbedded) {
+    ctx.registerMobileButton({
+      id: "notification-dropdown",
+      component: NotificationDropdown,
+      icon: "lucide-bell",
+      order: 10,
+      isVisible: true,
+    });
   }
+
+  // Settings menu items
+  ctx.registerSettingsMenuItem({ id: "theme-selector", component: ThemeSelector, group: "preferences", order: 10 });
+  ctx.registerSettingsMenuItem({ id: "language-selector", component: LanguageSelector, group: "preferences", order: 20 });
+  ctx.registerSettingsMenuItem({ id: "change-password", component: ChangePasswordButton, group: "account", order: 30 });
+  ctx.registerSettingsMenuItem({ id: "logout", component: LogoutButton, group: "account", order: 100 });
+
+  // Shell indicator state for SidebarHeader
+  provide(ShellIndicatorsKey, computed(() => hasUnreadNotifications.value));
 }

package/ui/components/organisms/vc-app/composables/useShellLifecycle.ts

@@ -1,7 +1,7 @@
 import { ref, watch, onUnmounted } from "vue";
-import { useNotifications } from "../../../../../core/composables";
-import { useUserManagement } from "../../../../../core/composables/useUserManagement";
-import { useAppSwitcher } from "../../../../../shared/components/app-switcher/composables/useAppSwitcher";
+import { useNotifications } from "@core/composables";
+import { useUserManagement } from "@core/composables/useUserManagement";
+import { useAppSwitcher } from "@shared/components/app-switcher/composables/useAppSwitcher";
 
 /**
  * Manages app readiness and authentication lifecycle.

package/ui/components/organisms/vc-app/composables/useShellNavigation.ts

@@ -1,7 +1,7 @@
 import { useRoute, useRouter } from "vue-router";
-import { useBladeNavigation } from "../../../../../shared/components";
-import { createLogger } from "../../../../../core/utilities";
-import type { MenuItem } from "../../../../../core/types";
+import { useBladeNavigation } from "@shared/components";
+import { createLogger } from "@core/utilities";
+import type { MenuItem } from "@core/types";
 
 const logger = createLogger("useShellNavigation");
 

package/ui/components/organisms/vc-app/composition/app-bar/index.ts

@@ -1,6 +1,6 @@
-export { default as VcAppMenuSidebar } from "../../_internal/app-bar/components/MenuSidebar.vue";
-export { default as VcAppBarMobileActions } from "../../_internal/app-bar/components/AppBarMobileActions.vue";
-export { default as VcAppBarOverlay } from "../../_internal/app-bar/components/AppBarOverlay.vue";
-export { default as VcAppBarWidgetContent } from "../../_internal/app-bar/components/AppBarWidgetContent.vue";
-export { default as VcAppBarWidgetItem } from "../../_internal/app-bar/components/AppBarWidgetItem.vue";
-export { default as VcAppBarWidgetsMenu } from "../../_internal/app-bar/components/AppBarWidgetsMenu.vue";
+export { default as VcAppMenuSidebar } from "@ui/components/organisms/vc-app/_internal/app-bar/components/MenuSidebar.vue";
+export { default as VcAppBarMobileActions } from "@ui/components/organisms/vc-app/_internal/app-bar/components/AppBarMobileActions.vue";
+export { default as VcAppBarOverlay } from "@ui/components/organisms/vc-app/_internal/app-bar/components/AppBarOverlay.vue";
+export { default as VcAppBarWidgetContent } from "@ui/components/organisms/vc-app/_internal/app-bar/components/AppBarWidgetContent.vue";
+export { default as VcAppBarWidgetItem } from "@ui/components/organisms/vc-app/_internal/app-bar/components/AppBarWidgetItem.vue";
+export { default as VcAppBarWidgetsMenu } from "@ui/components/organisms/vc-app/_internal/app-bar/components/AppBarWidgetsMenu.vue";

package/ui/components/organisms/vc-app/composition/index.ts

@@ -1,6 +1,6 @@
-export * from "./layouts";
-export * from "./sidebar";
-export * from "./menu";
-export * from "./app-bar";
-export * from "./state";
-export * from "./shell";
+export * from "@ui/components/organisms/vc-app/composition/layouts";
+export * from "@ui/components/organisms/vc-app/composition/sidebar";
+export * from "@ui/components/organisms/vc-app/composition/menu";
+export * from "@ui/components/organisms/vc-app/composition/app-bar";
+export * from "@ui/components/organisms/vc-app/composition/state";
+export * from "@ui/components/organisms/vc-app/composition/shell";

package/ui/components/organisms/vc-app/composition/layouts/index.ts

@@ -1,2 +1,2 @@
-export { default as VcAppDesktopLayout } from "../../_internal/layouts/DesktopLayout.vue";
-export { default as VcAppMobileLayout } from "../../_internal/layouts/MobileLayout.vue";
+export { default as VcAppDesktopLayout } from "@ui/components/organisms/vc-app/_internal/layouts/DesktopLayout.vue";
+export { default as VcAppMobileLayout } from "@ui/components/organisms/vc-app/_internal/layouts/MobileLayout.vue";

package/ui/components/organisms/vc-app/composition/menu/index.ts

@@ -1,6 +1,6 @@
-export { default as VcAppMenu } from "../../_internal/menu/VcAppMenu.vue";
-export { default as VcAppMenuGroup } from "../../_internal/menu/VcAppMenuGroup.vue";
-export { default as VcAppMenuItem } from "../../_internal/menu/VcAppMenuItem.vue";
+export { default as VcAppMenu } from "@ui/components/organisms/vc-app/_internal/menu/VcAppMenu.vue";
+export { default as VcAppMenuGroup } from "@ui/components/organisms/vc-app/_internal/menu/VcAppMenuGroup.vue";
+export { default as VcAppMenuItem } from "@ui/components/organisms/vc-app/_internal/menu/VcAppMenuItem.vue";
 
-export { useMenuActiveState, stripTenantPrefix } from "../../_internal/menu/composables/useMenuActiveState";
-export { useBadge } from "../../_internal/menu/composables/useBadge";
+export { useMenuActiveState, stripTenantPrefix } from "@ui/components/organisms/vc-app/_internal/menu/composables/useMenuActiveState";
+export { useBadge } from "@ui/components/organisms/vc-app/_internal/menu/composables/useBadge";

package/ui/components/organisms/vc-app/composition/shell/index.ts

@@ -1,3 +1,3 @@
-export { useShellBootstrap } from "../../composables/useShellBootstrap";
-export { useShellLifecycle } from "../../composables/useShellLifecycle";
-export { useShellNavigation } from "../../composables/useShellNavigation";
+export { useShellBootstrap } from "@ui/components/organisms/vc-app/composables/useShellBootstrap";
+export { useShellLifecycle } from "@ui/components/organisms/vc-app/composables/useShellLifecycle";
+export { useShellNavigation } from "@ui/components/organisms/vc-app/composables/useShellNavigation";

package/ui/components/organisms/vc-app/composition/sidebar/index.ts

@@ -1,3 +1,3 @@
-export { default as VcAppSidebarHeader } from "../../_internal/sidebar/SidebarHeader.vue";
-export { default as VcAppSidebarContent } from "../../_internal/sidebar/SidebarContent.vue";
-export { default as VcAppSidebarCollapseButton } from "../../_internal/sidebar/SidebarCollapseButton.vue";
+export { default as VcAppSidebarHeader } from "@ui/components/organisms/vc-app/_internal/sidebar/SidebarHeader.vue";
+export { default as VcAppSidebarContent } from "@ui/components/organisms/vc-app/_internal/sidebar/SidebarContent.vue";
+export { default as VcAppSidebarCollapseButton } from "@ui/components/organisms/vc-app/_internal/sidebar/SidebarCollapseButton.vue";

package/ui/components/organisms/vc-app/composition/state/index.ts

@@ -1,6 +1,6 @@
-export { provideSidebarState, useSidebarState } from "../../composables/useSidebarState";
+// provideSidebarState and useSidebarState are now exported from core/composables/useSidebarState
 
-export { provideAppBarState, useAppBarState } from "../../_internal/app-bar/composables/useAppBarState";
-export { useAppBarWidgets } from "../../_internal/app-bar/composables/useAppBarWidgets";
-export { useAppBarMobileActions } from "../../_internal/app-bar/composables/useAppBarMobileActions";
-export { useToggleableContent } from "../../_internal/app-bar/composables/useToggleableContent";
+export { provideAppBarState, useAppBarState } from "@ui/components/organisms/vc-app/_internal/app-bar/composables/useAppBarState";
+export { useAppBarWidgets } from "@ui/components/organisms/vc-app/_internal/app-bar/composables/useAppBarWidgets";
+export { useAppBarMobileActions } from "@ui/components/organisms/vc-app/_internal/app-bar/composables/useAppBarMobileActions";
+export { useToggleableContent } from "@ui/components/organisms/vc-app/_internal/app-bar/composables/useToggleableContent";

package/ui/components/organisms/vc-app/index.ts

@@ -1,2 +1,2 @@
-export { default as VcApp } from "./vc-app.vue";
-export * from "./composition";
+export { default as VcApp } from "@ui/components/organisms/vc-app/vc-app.vue";
+export * from "@ui/components/organisms/vc-app/composition";