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

package/core/services/dashboard-service.ts

@@ -1,9 +1,5 @@
 import { reactive, Component } from "vue";
-import { DashboardServiceKey } from "../../injection-keys";
-import { usePermissions } from "../composables/usePermissions";
-import { createLogger } from "../utilities";
-
-const logger = createLogger("dashboard-service");
+import { createPreregistrationBus } from "./_internal";
 
 export interface DashboardWidgetSize {
   width: number;
@@ -29,20 +25,24 @@ export interface IDashboardService {
   registerWidget: (widget: DashboardWidget) => void;
   getWidgets: () => DashboardWidget[];
   updateWidgetPosition: (widgetId: string, position: DashboardWidgetPosition) => void;
-  getLayout: () => Map<string, DashboardWidgetPosition>;
+  getLayout: () => ReadonlyMap<string, DashboardWidgetPosition>;
 }
 
-// Global state for pre-registering widgets
-const preregisteredWidgets: DashboardWidget[] = [];
+export interface CreateDashboardServiceOptions {
+  hasAccess?: (permissions: string[] | undefined) => boolean;
+}
+
+export const dashboardBus = createPreregistrationBus<DashboardWidget, IDashboardService>({
+  name: "dashboard-service",
+  getKey: (widget) => widget.id,
+  registerIntoService: (service, widget) => service.registerWidget(widget),
+});
 
 /**
- * Registers a widget before the service is initialized
+ * Registers a widget before the service is initialized.
  */
 export function registerDashboardWidget(widget: DashboardWidget): void {
-  const existingWidget = preregisteredWidgets.find((w) => w.id === widget.id);
-  if (!existingWidget) {
-    preregisteredWidgets.push(widget);
-  }
+  dashboardBus.preregister(widget);
 }
 
 const createState = () => ({
@@ -51,41 +51,38 @@ const createState = () => ({
 });
 
 /**
- * Creates a service for managing dashboard widgets
+ * Creates a service for managing dashboard widgets.
  */
-export function createDashboardService(): IDashboardService {
+export function createDashboardService(options: CreateDashboardServiceOptions = {}): IDashboardService {
   const state = createState();
-  const { hasAccess } = usePermissions();
+  const hasAccess = options.hasAccess ?? (() => true);
 
   const registerWidget = (widget: DashboardWidget): void => {
     if (state.widgets.has(widget.id)) {
       throw new Error(`Widget with id ${widget.id} already registered`);
     }
 
-    state.widgets.set(widget.id, widget);
+    state.widgets.set(widget.id, {
+      ...widget,
+      permissions: widget.permissions ? [...widget.permissions] : undefined,
+      position: widget.position ? { ...widget.position } : undefined,
+      props: widget.props ? { ...widget.props } : undefined,
+    });
 
-    // If the position is not specified, we don't set it here
-    // The DraggableDashboard component will handle finding a free position
     if (widget.position) {
-      state.layout.set(widget.id, widget.position);
+      state.layout.set(widget.id, { ...widget.position });
     }
-    // If no position is specified, the widget will be placed by the dashboard component
-    // to avoid collisions with existing widgets
   };
 
-  /**
-   * Returns a list of widgets with access rights
-   */
   const getWidgets = (): DashboardWidget[] => {
-    return Array.from(state.widgets.values()).filter((widget) => {
-      // If the widget has no permissions requirements, show it to everyone
-      if (!widget.permissions || widget.permissions.length === 0) {
-        return true;
-      }
-
-      // Check if the user has the necessary permissions
-      return hasAccess(widget.permissions);
-    });
+    return Array.from(state.widgets.values())
+      .filter((widget) => !widget.permissions || widget.permissions.length === 0 || hasAccess(widget.permissions))
+      .map((widget) => ({
+        ...widget,
+        permissions: widget.permissions ? [...widget.permissions] : undefined,
+        position: widget.position ? { ...widget.position } : undefined,
+        props: widget.props ? { ...widget.props } : undefined,
+      }));
   };
 
   const updateWidgetPosition = (widgetId: string, position: DashboardWidgetPosition): void => {
@@ -93,26 +90,21 @@ export function createDashboardService(): IDashboardService {
       throw new Error(`Widget with id ${widgetId} not found`);
     }
 
-    state.layout.set(widgetId, position);
+    state.layout.set(widgetId, { ...position });
   };
 
-  const getLayout = (): Map<string, DashboardWidgetPosition> => {
-    return state.layout;
+  const getLayout = (): ReadonlyMap<string, DashboardWidgetPosition> => {
+    return new Map(state.layout);
   };
 
-  // Register pre-registered widgets
-  preregisteredWidgets.forEach((widget) => {
-    try {
-      registerWidget(widget);
-    } catch (e) {
-      logger.warn(`Failed to register preregistered widget ${widget.id}:`, e);
-    }
-  });
-
-  return {
+  const service: IDashboardService = {
     registerWidget,
     getWidgets,
     updateWidgetPosition,
     getLayout,
   };
+
+  dashboardBus.replayInto(service);
+
+  return service;
 }

package/core/services/global-search-service/global-search-service.md

@@ -1,203 +1,28 @@
-# Global Search Service Documentation
+# Global Search Service
 
-The Global Search Service is a core component of the VC-Shell framework that provides a centralized mechanism for implementing search functionality across the application. It allows registering search providers and executing search operations with visibility control.
+## Purpose
+`createGlobalSearchService` keeps search visibility state and search query text per blade.
 
-## Overview
+## Source
+`framework/core/services/global-search-service/index.ts`
 
-The Global Search Service facilitates the implementation of search functionality throughout the application, managing search visibility states and provider registration. It's particularly useful for mobile interfaces where search views need to be toggled.
+## API
 
-## File Path
-`/framework/core/services/global-search-service.ts`
-
-## Core Interfaces
-
-While the complete interfaces aren't shown in the snippets, we can infer the following from usage:
-
-```typescript
-export interface IGlobalSearchService {
+```ts
+interface GlobalSearchState {
   isSearchVisible: Ref<Record<string, boolean>>;
-  toggleSearch: (bladeId: string) => void;
-  closeSearch: (bladeId: string) => void;
-  // Likely additional methods for search provider registration and query execution
+  searchQuery: Ref<Record<string, string>>;
+  toggleSearch(bladeId: string): void;
+  setSearchQuery(bladeId: string, query: string): void;
+  closeSearch(bladeId: string): void;
 }
 ```
 
-## Primary Features
-
-### Search Visibility Management
-
-The service tracks whether search functionality is visible on different blades and provides methods to toggle this visibility.
-
-```typescript
-// Toggle search visibility for a specific blade
-globalSearchService.toggleSearch('blade-123');
-
-// Explicitly close search for a blade
-globalSearchService.closeSearch('blade-123');
-
-// Check if search is visible for a blade
-const isVisible = globalSearchService.isSearchVisible.value['blade-123'];
-```
-
-### Integration with Mobile UI
-
-The service is particularly useful for controlling search visibility in mobile interfaces, where screen real estate is limited and search often needs to be toggled.
-
-## Usage in Components
-
-The Global Search Service is accessed through the `useGlobalSearch` composable. Here's a real-world example from the `vc-table-header` component:
-
-```typescript
-// From framework/ui/components/organisms/vc-table/_internal/vc-table-header/vc-table-header.vue
-<script lang="ts" setup>
-import { VNode, computed, inject, Ref, h, useSlots, onBeforeUnmount, onMounted, ref } from "vue";
-import { useGlobalSearch } from "../../../../../../core/composables/useGlobalSearch";
-import { useAppBarMobileButtons } from "../../../../../../core/composables/useAppBarMobileButtons";
-import { SearchIcon } from "../../../../atoms/vc-icon/icons";
-import { FALLBACK_BLADE_ID } from "../../../../../../core/constants";
-
-const props = defineProps<{
-  // Component props
-  hasHeaderSlot: boolean;
-  header: boolean;
-  columnsInit: boolean;
-  searchValue?: string;
-  // other props...
-}>();
-
-const blade = inject(
-  BladeInstance,
-  computed(
-    (): Partial<IBladeInstance> => ({
-      navigation: {
-        idx: 0,
-        instance: null,
-      },
-    }),
-  ),
-);
-const globalSearch = useGlobalSearch();
-const isMobile = inject("isMobile") as Ref<boolean>;
-const { register: registerMobileButton, unregister: unregisterMobileButton } = useAppBarMobileButtons();
-
-const currentBladeId = computed(() => {
-  return blade?.value?.id || 0;
-});
-
-// Determine if search should be shown based on mobile state and search visibility
-const shouldShowSearch = computed(() => {
-  if (!isMobile.value) return true;
-
-  if (blade?.value.navigation?.idx === 0) {
-    return globalSearch.isSearchVisible.value[currentBladeId.value];
-  }
-
-  return true;
-});
-
-const bladeId = computed(() => {
-  return blade.value?.id || FALLBACK_BLADE_ID;
-});
-
-// Configure search button for mobile view
-const searchButtonConfig = ref({
-  id: "global-search",
-  icon: SearchIcon,
-  onClick: () => {
-    globalSearch.toggleSearch(bladeId.value);
-  },
-  onClose: () => {
-    globalSearch.closeSearch(bladeId.value);
-  },
-  // Button is visible only if:
-  // 1. We are in the root blade (idx === 0)
-  // 2. Header is available for display
-  isVisible: computed(() => Boolean(blade.value?.navigation?.idx === 0 && showHeader.value)),
-  order: 5,
-});
-
-// Register search button when mounted
-onMounted(() => {
-  if (props.hasHeaderSlot || props.header) {
-    registerMobileButton(searchButtonConfig.value);
-  }
-});
-
-// Close search and unregister button when unmounted
-onBeforeUnmount(() => {
-  if (globalSearch.isSearchVisible.value[bladeId.value]) {
-    globalSearch.closeSearch(bladeId.value);
-  }
-  unregisterMobileButton("global-search");
-});
-</script>
-```
-
-This implementation displays how the Global Search Service:
-
-1. Controls search visibility based on the current blade and mobile state
-2. Integrates with mobile buttons for toggling search
-3. Automatically handles cleanup when components are unmounted
-
-## Template Integration
-
-The search functionality is conditionally displayed based on the visibility state managed by the service:
-
-```vue
-<template>
-  <Transition name="table-header">
-    <div
-      v-if="showHeader && shouldShowSearch"
-      class="vc-table-header"
-    >
-      <slot
-        name="header"
-        :header="headerComponent"
-      >
-        <component :is="headerComponent" />
-      </slot>
-    </div>
-  </Transition>
-</template>
-```
-
-## Mobile Integration
-
-The search button is registered with the App Bar Mobile Buttons Service to provide a consistent way to toggle search on mobile devices:
-
-```typescript
-// Register search button when component is mounted
-onMounted(() => {
-  if (props.hasHeaderSlot || props.header) {
-    registerMobileButton({
-      id: "global-search",
-      icon: SearchIcon,
-      onClick: () => {
-        globalSearch.toggleSearch(bladeId.value);
-      },
-      onClose: () => {
-        globalSearch.closeSearch(bladeId.value);
-      },
-      isVisible: computed(() => Boolean(blade.value?.navigation?.idx === 0 && showHeader.value)),
-      order: 5,
-    });
-  }
-});
-```
-
-## Best Practices
-
-1. **Blade-Specific Search**: Always associate search state with specific blade IDs to ensure each blade can have independent search visibility.
-
-2. **Mobile Considerations**: Implement different search behavior for mobile versus desktop views, using the isMobile flag.
-
-3. **Cleanup**: Always close search and unregister any associated UI elements when components unmount.
-
-4. **Search Toggling**: Use the toggleSearch method for buttons that need to both open and close search, rather than implementing toggle logic yourself.
-
-5. **Default Visibility**: In desktop views, typically keep search visible by default, only using toggle behavior on mobile.
-
-## Related Composables
+## Behavior
+- State is scoped to a service instance.
+- `toggleSearch` flips visibility for a blade key.
+- `closeSearch` always sets visibility to `false`.
+- `setSearchQuery` updates the per-blade query string.
 
-- `useGlobalSearch`: Provides access to the Global Search Service within Vue components.
-- `provideGlobalSearchService`: Creates and provides the Global Search Service to the component tree. 
+## Usage
+Use via `useGlobalSearch` / `provideGlobalSearch` composables.

package/core/services/language-dashboard-service.test.ts

@@ -0,0 +1,183 @@
+import { describe, it, expect, vi } from "vitest";
+
+async function loadLanguageServiceModule() {
+  vi.resetModules();
+  return import("./language-service");
+}
+
+async function loadDashboardServiceModule() {
+  vi.resetModules();
+  return import("./dashboard-service");
+}
+
+describe("language-service", () => {
+  it("resolves unknown locales to 'en'", async () => {
+    const { createLanguageService } = await loadLanguageServiceModule();
+    localStorage.removeItem("VC_LANGUAGE_SETTINGS");
+    const service = createLanguageService();
+
+    expect(service.resolveCamelCaseLocale("zzZZ")).toBe("en");
+  });
+
+  it("falls back to a supported locale in setLocale", async () => {
+    const { createLanguageService } = await loadLanguageServiceModule();
+    localStorage.removeItem("VC_LANGUAGE_SETTINGS");
+    const service = createLanguageService();
+
+    service.setLocale("zzZZ");
+
+    expect(service.currentLocale.value).toBe("en");
+  });
+});
+
+describe("dashboard-service", () => {
+  it("works without implicit composable dependencies and supports injected access checks", async () => {
+    const { createDashboardService } = await loadDashboardServiceModule();
+
+    const permissiveService = createDashboardService();
+    permissiveService.registerWidget({
+      id: "widget-1",
+      name: "Widget 1",
+      component: {} as any,
+      size: { width: 1, height: 1 },
+      permissions: ["can-read"],
+    });
+
+    expect(permissiveService.getWidgets()).toHaveLength(1);
+
+    const restrictiveService = createDashboardService({ hasAccess: () => false });
+    restrictiveService.registerWidget({
+      id: "widget-2",
+      name: "Widget 2",
+      component: {} as any,
+      size: { width: 1, height: 1 },
+      permissions: ["can-read"],
+    });
+
+    expect(restrictiveService.getWidgets()).toHaveLength(0);
+  });
+
+  it("returns a copy of layout map from getLayout", async () => {
+    const { createDashboardService } = await loadDashboardServiceModule();
+    const service = createDashboardService();
+
+    service.registerWidget({
+      id: "widget-1",
+      name: "Widget 1",
+      component: {} as any,
+      size: { width: 1, height: 1 },
+      position: { x: 0, y: 0 },
+    });
+
+    const layout = service.getLayout() as Map<string, { x: number; y: number }>;
+    layout.set("external-mutation", { x: 100, y: 100 });
+
+    expect(service.getLayout().has("external-mutation")).toBe(false);
+  });
+
+  it("throws on duplicate widget ID", async () => {
+    const { createDashboardService } = await loadDashboardServiceModule();
+    const service = createDashboardService();
+
+    service.registerWidget({
+      id: "dup",
+      name: "First",
+      component: {} as any,
+      size: { width: 1, height: 1 },
+    });
+
+    expect(() =>
+      service.registerWidget({
+        id: "dup",
+        name: "Second",
+        component: {} as any,
+        size: { width: 1, height: 1 },
+      }),
+    ).toThrow("Widget with id dup already registered");
+  });
+
+  it("updates widget position", async () => {
+    const { createDashboardService } = await loadDashboardServiceModule();
+    const service = createDashboardService();
+
+    service.registerWidget({
+      id: "w1",
+      name: "Widget",
+      component: {} as any,
+      size: { width: 1, height: 1 },
+      position: { x: 0, y: 0 },
+    });
+
+    service.updateWidgetPosition("w1", { x: 5, y: 10 });
+    const layout = service.getLayout();
+    expect(layout.get("w1")).toEqual({ x: 5, y: 10 });
+  });
+
+  it("throws on updating position for non-existent widget", async () => {
+    const { createDashboardService } = await loadDashboardServiceModule();
+    const service = createDashboardService();
+
+    expect(() => service.updateWidgetPosition("nonexistent", { x: 0, y: 0 })).toThrow(
+      "Widget with id nonexistent not found",
+    );
+  });
+
+  it("preregistration deduplicates by widget id", async () => {
+    const { registerDashboardWidget, createDashboardService } = await loadDashboardServiceModule();
+
+    registerDashboardWidget({
+      id: "pre-w",
+      name: "V1",
+      component: {} as any,
+      size: { width: 1, height: 1 },
+    });
+    registerDashboardWidget({
+      id: "pre-w",
+      name: "V2",
+      component: {} as any,
+      size: { width: 1, height: 1 },
+    });
+
+    const service = createDashboardService();
+    // Bus deduplicates preregistered items, so only V2 is replayed
+    expect(service.getWidgets()).toHaveLength(1);
+    expect(service.getWidgets()[0].name).toBe("V2");
+  });
+
+  it("disposes service instance via bus", async () => {
+    const { createDashboardService, dashboardBus } = await loadDashboardServiceModule();
+    const service = createDashboardService();
+
+    expect(dashboardBus.instanceCount).toBe(1);
+    dashboardBus.dispose(service);
+    expect(dashboardBus.instanceCount).toBe(0);
+  });
+
+  it("filters widgets by permissions", async () => {
+    const { createDashboardService } = await loadDashboardServiceModule();
+
+    const service = createDashboardService({
+      hasAccess: (perms) => perms?.includes("admin") ?? false,
+    });
+
+    service.registerWidget({
+      id: "admin-widget",
+      name: "Admin Only",
+      component: {} as any,
+      size: { width: 1, height: 1 },
+      permissions: ["admin"],
+    });
+
+    service.registerWidget({
+      id: "public-widget",
+      name: "Public",
+      component: {} as any,
+      size: { width: 1, height: 1 },
+    });
+
+    const widgets = service.getWidgets();
+    expect(widgets).toHaveLength(2);
+    expect(widgets.map((w) => w.id)).toContain("admin-widget");
+    expect(widgets.map((w) => w.id)).toContain("public-widget");
+  });
+});

package/core/services/language-service.ts

@@ -22,6 +22,15 @@ export interface ILanguageService {
 export function createLanguageService(): ILanguageService {
   const savedLocale = useLocalStorage("VC_LANGUAGE_SETTINGS", "");
 
+  function resolveSupportedLocale(locale: string): string {
+    if (!locale) {
+      return "en";
+    }
+
+    const normalizedLocale = locale.replace(/([a-z]+)([A-Z]+)/g, "$1-$2").toLowerCase();
+    return i18n.global.availableLocales.includes(normalizedLocale) ? normalizedLocale : "en";
+  }
+
   // Initialize locale from localStorage on service creation
   if (savedLocale.value && i18n.global.availableLocales.includes(savedLocale.value)) {
     i18n.global.locale.value = savedLocale.value;
@@ -36,16 +45,22 @@ export function createLanguageService(): ILanguageService {
   });
 
   function setLocale(locale: string) {
+    const resolvedLocale = resolveSupportedLocale(locale);
+
     // Update the global i18n locale
-    i18n.global.locale.value = locale;
+    i18n.global.locale.value = resolvedLocale;
+
+    const localeMessages = (i18n.global.getLocaleMessage(resolvedLocale) as { messages?: Record<string, string> })
+      ?.messages;
 
     veeValidate.configure({
-      generateMessage: localize(locale, {
-        messages: (i18n.global.getLocaleMessage(locale) as { messages: Record<string, string> }).messages,
+      generateMessage: localize(resolvedLocale, {
+        messages: localeMessages ?? {},
       }),
     });
-    setVeeI18nLocale(locale);
-    savedLocale.value = locale;
+
+    setVeeI18nLocale(resolvedLocale);
+    savedLocale.value = resolvedLocale;
   }
 
   function getLocaleByTag(localeTag: string) {
@@ -57,17 +72,12 @@ export function createLanguageService(): ILanguageService {
   }
 
   function resolveCamelCaseLocale(locale: string) {
-    const formattedLocale = locale.replace(/([a-z]+)([A-Z]+)/g, "$1-$2").toLowerCase();
-
-    if (i18n.global.getLocaleMessage(formattedLocale)) {
-      return formattedLocale;
-    }
-    return "en";
+    return resolveSupportedLocale(locale);
   }
 
   function getCountryCode(language: string): string {
     return (
-      languageToCountryMap[language.toLocaleLowerCase()] || languageToCountryMap[language.slice(0, 2)] || "xx" // placeholder for unknown country
+      languageToCountryMap[language.toLowerCase()] || languageToCountryMap[language.slice(0, 2)] || "xx" // placeholder for unknown country
     );
   }