@vc-shell/framework 1.1.24 → 1.1.26

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [1.1.26](https://github.com/VirtoCommerce/vc-shell/compare/v1.1.25...v1.1.26) (2025-06-04)
+
+
+### Features
+
+* **global-search:** add useGlobalSearch composable and Global Search Service documentation for enhanced search functionality across the application ([e53be10](https://github.com/VirtoCommerce/vc-shell/commit/e53be1095b2b7067dc3ad9ce9f1ab23aafaa57a2))
+* **localization:** add theme localization support for German and English languages ([8d8fdb0](https://github.com/VirtoCommerce/vc-shell/commit/8d8fdb0a05814ea277f7ab07978902ae86ec3102))
+* **vc-popup:** add Storybook stories for VcPopup component, showcasing various configurations and customization options ([dc8e961](https://github.com/VirtoCommerce/vc-shell/commit/dc8e961be32469b7a06fed78aa68846ba95a1d70))
+
+
+
+## [1.1.25](https://github.com/VirtoCommerce/vc-shell/compare/v1.1.24...v1.1.25) (2025-05-30)
+
+
+
 ## [1.1.24](https://github.com/VirtoCommerce/vc-shell/compare/v1.1.23...v1.1.24) (2025-05-29)
 
 

package/core/composables/useAppInsights/index.ts

@@ -1,7 +1,7 @@
 import { inject } from "vue";
 import { AppInsightsPluginOptions, useAppInsights as useInsights } from "vue3-application-insights";
 import { generateW3CId } from "@microsoft/applicationinsights-core-js";
-import { useUser } from "./../useUser";
+import { useUserManagement } from "./../useUserManagement";
 import { ApplicationInsights, Snippet } from "@microsoft/applicationinsights-web";
 
 export interface IUseAppInsights {
@@ -14,7 +14,7 @@ export interface IUseAppInsights {
 
 export function useAppInsights(): IUseAppInsights {
   const appInsights = useInsights();
-  const { user } = useUser();
+  const { user } = useUserManagement();
   const appInsightsOptions = inject<AppInsightsPluginOptions>("appInsightsOptions");
 
   function setupPageTracking() {

package/core/composables/useErrorHandler/index.ts

@@ -1,5 +1,6 @@
 import { onErrorCaptured, getCurrentInstance, ref, Ref } from "vue";
-import { useAppInsights, useUser } from "..";
+import { useAppInsights } from "..";
+import { useUserManagement } from "../useUserManagement";
 
 interface IUseErrorHandler {
   error: Ref<string | null>;
@@ -10,7 +11,7 @@ export function useErrorHandler(capture?: boolean): IUseErrorHandler {
   const error = ref<string | null>(null);
   const instance = getCurrentInstance();
   const { appInsights } = useAppInsights();
-  const { user } = useUser();
+  const { user } = useUserManagement();
 
   function reset() {
     error.value = null;

package/core/composables/useGlobalSearch/useGlobalSearch.md

@@ -0,0 +1,263 @@
+# useGlobalSearch Composable
+
+The `useGlobalSearch` composable provides access to the Global Search Service, allowing components to manage search functionality across the application, particularly for blade-based interfaces.
+
+## Overview
+
+The `useGlobalSearch` composable is a core utility for managing search visibility and query state in VC-Shell applications. It's particularly useful for controlling search UI in blade components and handling mobile-specific search behavior.
+
+## API Reference
+
+### Return Value
+
+The `useGlobalSearch` composable returns the global search state object with the following properties and methods:
+
+```typescript
+interface GlobalSearchState {
+  isSearchVisible: Ref<Record<string, boolean>>;  // Tracks search visibility by blade ID
+  searchQuery: Ref<Record<string, string>>;       // Stores search queries by blade ID
+  toggleSearch: (bladeId: string) => void;        // Toggles search visibility for a blade
+  setSearchQuery: (bladeId: string, query: string) => void;  // Sets the search query for a blade
+  closeSearch: (bladeId: string) => void;         // Closes search for a specific blade
+}
+```
+
+### Methods
+
+#### toggleSearch
+
+Toggles search visibility for a specific blade.
+
+```typescript
+toggleSearch(bladeId: string): void
+```
+
+- `bladeId`: The ID of the blade to toggle search visibility for
+
+#### setSearchQuery
+
+Sets the search query for a specific blade.
+
+```typescript
+setSearchQuery(bladeId: string, query: string): void
+```
+
+- `bladeId`: The ID of the blade
+- `query`: The search query string
+
+#### closeSearch
+
+Explicitly closes search for a specific blade.
+
+```typescript
+closeSearch(bladeId: string): void
+```
+
+- `bladeId`: The ID of the blade to close search for
+
+### Properties
+
+#### isSearchVisible
+
+A reactive reference to an object that tracks search visibility state for each blade by ID.
+
+```typescript
+isSearchVisible: Ref<Record<string, boolean>>
+```
+
+#### searchQuery
+
+A reactive reference to an object that stores search queries for each blade by ID.
+
+```typescript
+searchQuery: Ref<Record<string, string>>
+```
+
+## Usage
+
+### Basic Usage in a Component
+
+```typescript
+import { useGlobalSearch } from '@vc-shell/framework';
+import { computed, inject } from 'vue';
+
+export default {
+  setup() {
+    // Get the blade ID (typically injected in blade components)
+    const blade = inject('BladeInstance');
+    const bladeId = computed(() => blade.value?.id || 'fallback-id');
+    
+    // Get global search functionality
+    const globalSearch = useGlobalSearch();
+    
+    // Determine if search should be shown
+    const isSearchVisible = computed(() => {
+      return globalSearch.isSearchVisible.value[bladeId.value] || false;
+    });
+    
+    // Function to toggle search
+    function toggleSearch() {
+      globalSearch.toggleSearch(bladeId.value);
+    }
+    
+    // Function to update search query
+    function updateSearchQuery(query) {
+      globalSearch.setSearchQuery(bladeId.value, query);
+    }
+    
+    return {
+      isSearchVisible,
+      toggleSearch,
+      updateSearchQuery
+    };
+  }
+}
+```
+
+### Table Component with Search
+
+```vue
+<template>
+  <div class="data-table-component">
+    <!-- Search Input -->
+    <div v-if="shouldShowSearch" class="search-container">
+      <input 
+        type="text" 
+        v-model="searchInput" 
+        placeholder="Search..." 
+        @input="handleSearchInput"
+      />
+    </div>
+    
+    <!-- Table Content -->
+    <table>
+      <!-- Table structure -->
+    </table>
+    
+    <!-- Mobile Search Button -->
+    <button 
+      v-if="isMobile" 
+      class="mobile-search-button"
+      @click="toggleSearch"
+    >
+      Search
+    </button>
+  </div>
+</template>
+
+<script setup>
+import { ref, computed, inject, watch } from 'vue';
+import { useGlobalSearch } from '@vc-shell/framework';
+
+// Get mobile state
+const isMobile = inject('isMobile', ref(false));
+
+// Get blade and global search
+const blade = inject('BladeInstance');
+const bladeId = computed(() => blade.value?.id || 'fallback-id');
+const globalSearch = useGlobalSearch();
+
+// Track search input
+const searchInput = ref('');
+
+// Determine if search should be visible
+const shouldShowSearch = computed(() => {
+  if (!isMobile.value) return true;
+  return globalSearch.isSearchVisible.value[bladeId.value];
+});
+
+// Watch for changes in the global search query
+watch(() => globalSearch.searchQuery.value[bladeId.value], (newQuery) => {
+  if (newQuery !== undefined) {
+    searchInput.value = newQuery;
+  }
+});
+
+// Toggle search visibility
+function toggleSearch() {
+  globalSearch.toggleSearch(bladeId.value);
+}
+
+// Handle search input changes
+function handleSearchInput() {
+  globalSearch.setSearchQuery(bladeId.value, searchInput.value);
+  // Additional search logic
+}
+</script>
+```
+
+### Mobile Search Button Implementation
+
+```typescript
+import { useGlobalSearch } from '@vc-shell/framework';
+import { useAppBarMobileButtons } from '@vc-shell/framework';
+import { computed, onMounted, onBeforeUnmount } from 'vue';
+
+export default {
+  setup() {
+    const bladeId = computed(() => 'your-blade-id');
+    const globalSearch = useGlobalSearch();
+    const { register: registerMobileButton, unregister: unregisterMobileButton } = useAppBarMobileButtons();
+    
+    // Register a search button in the mobile app bar
+    onMounted(() => {
+      registerMobileButton({
+        id: "global-search",
+        icon: "search-icon",
+        onClick: () => {
+          globalSearch.toggleSearch(bladeId.value);
+        },
+        onClose: () => {
+          globalSearch.closeSearch(bladeId.value);
+        },
+        isVisible: computed(() => true), // Button visibility logic
+        order: 5, // Order in the mobile button list
+      });
+    });
+    
+    // Cleanup when component is unmounted
+    onBeforeUnmount(() => {
+      if (globalSearch.isSearchVisible.value[bladeId.value]) {
+        globalSearch.closeSearch(bladeId.value);
+      }
+      unregisterMobileButton("global-search");
+    });
+  }
+}
+```
+
+## Provider Function
+
+In addition to the `useGlobalSearch` composable, there's a provider function to initialize the global search service in your application:
+
+```typescript
+import { provideGlobalSearch } from '@vc-shell/framework';
+
+export default {
+  setup() {
+    // Create and provide the global search service to the component tree
+    const globalSearchService = provideGlobalSearch();
+    
+    // Now child components can use useGlobalSearch()
+    
+    return {};
+  }
+}
+```
+
+## 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 Resources
+
+- [Global Search Service](../../services/global-search-service/global-search-service.md) - Documentation for the underlying service
+- [Blade Navigation](../navigation.md) - Information about the blade navigation system 

package/core/composables/usePermissions/index.ts

@@ -1,12 +1,12 @@
 import { Ref, ref } from "vue";
-import { useUser } from "./../useUser";
+import { useUserManagement } from "./../useUserManagement";
 
 interface IUsePermissions {
   hasAccess(permissions: string | string[] | undefined): boolean;
 }
 const userPermissions: Ref<string[]> = ref([]);
 export function usePermissions(): IUsePermissions {
-  const { user } = useUser();
+  const { user } = useUserManagement();
 
   if (user.value) {
     userPermissions.value = user.value?.permissions ?? [];

package/core/composables/useTheme/index.ts

@@ -1,47 +1,67 @@
 import { BasicColorSchema, useColorMode, useCycleList } from "@vueuse/core";
 import { computed, watchEffect, ref, type Ref } from "vue";
+import { useI18n } from "vue-i18n";
+import * as _ from "lodash-es";
+import { i18n } from "../../plugins/i18n";
+
+export interface ThemeDefinition {
+  key: string;
+  localizationKey?: string;
+}
+
+export interface DisplayTheme {
+  key: string;
+  name: string; // localized name
+}
 
 export interface IUseTheme {
-  themes: Ref<string[]>;
-  current: Ref<string>;
+  themes: Ref<DisplayTheme[]>;
+  currentThemeKey: Ref<string>;
+  currentLocalizedName: Ref<string>;
   next: () => void;
-  register: (customNames: string | string[]) => void;
-  unregister: (customNames: string | string[]) => void;
-  setTheme: (theme: string) => void;
+  register: (themesToAdd: ThemeDefinition | ThemeDefinition[]) => void;
+  unregister: (themeKeysToRemove: string | string[]) => void;
+  setTheme: (themeKey: string) => void;
 }
 
-const registeredThemes: Ref<string[]> = ref([
-  // "auto"
-]);
+// Initialize with a default "light" theme, assuming a convention for its localization key.
+const _themeRegistry: Ref<ThemeDefinition[]> = ref([{ key: "light", localizationKey: "CORE.THEMES.LIGHT" }]);
+
 export const useTheme = (): IUseTheme => {
-  function register(customNames: string | string[]) {
-    (typeof customNames === "string" ? [customNames] : customNames).forEach((name) => {
-      if (!registeredThemes.value.includes(name)) {
-        registeredThemes.value.push(name);
+  const { t } = i18n.global;
+
+  function register(themesToAdd: ThemeDefinition | ThemeDefinition[]) {
+    (Array.isArray(themesToAdd) ? themesToAdd : [themesToAdd]).forEach((themeDef) => {
+      if (!_themeRegistry.value.some((t) => t.key === themeDef.key)) {
+        _themeRegistry.value.push(themeDef);
       }
     });
   }
 
-  function unregister(customNames: string | string[]) {
-    (typeof customNames === "string" ? [customNames] : customNames).forEach((name) => {
-      const index = registeredThemes.value.indexOf(name);
+  function unregister(themeKeysToRemove: string | string[]) {
+    (Array.isArray(themeKeysToRemove) ? themeKeysToRemove : [themeKeysToRemove]).forEach((keyToRemove) => {
+      const index = _themeRegistry.value.findIndex((t) => t.key === keyToRemove);
       if (index >= 0) {
-        registeredThemes.value.splice(index, 1);
+        // Ensure we don't unregister the last theme if it's active, or handle active theme change.
+        // For simplicity now, just remove. Consider active theme implications if this is an issue.
+        // Especially if 'light' is removed and it's the initial/fallback.
+        // However, 'light' is added by default and this function is for custom themes.
+        _themeRegistry.value.splice(index, 1);
       }
     });
   }
 
-  function setTheme(theme: string) {
-    state.value = theme;
-  }
+  const themeKeys = computed(() => _themeRegistry.value.map((t) => t.key));
 
   const mode = useColorMode({
+    attribute: "data-theme",
     emitAuto: true,
-    initialValue: "light",
+    initialValue: "light", // Should align with a default theme in _themeRegistry
     modes: {
-      ...registeredThemes.value.reduce(
+      // Dynamically build modes from registered theme keys
+      ...themeKeys.value.reduce(
         (acc, name) => {
-          acc[name] = name;
+          acc[name] = name; // Maps theme key to itself (e.g., "ocean": "ocean")
           return acc;
         },
         {} as Record<string, string>,
@@ -49,13 +69,41 @@ export const useTheme = (): IUseTheme => {
     },
   });
 
-  const { state, next } = useCycleList(registeredThemes.value, { initialValue: mode });
+  const { state, next } = useCycleList(themeKeys, { initialValue: mode });
+
+  watchEffect(() => {
+    if (state.value) {
+      // Ensure state.value is not undefined
+      mode.value = state.value as BasicColorSchema; // state.value is a theme key
+    }
+  });
+
+  function setTheme(themeKey: string) {
+    if (themeKeys.value.includes(themeKey)) {
+      state.value = themeKey;
+    } else {
+      console.warn(`[useTheme] Attempted to set an unregistered theme: ${themeKey}`);
+    }
+  }
 
-  watchEffect(() => (mode.value = state.value as BasicColorSchema));
+  const currentLocalizedName = computed(() => {
+    const currentDef = _themeRegistry.value.find((t) => t.key === state.value);
+    if (currentDef) {
+      return currentDef.localizationKey ? t(currentDef.localizationKey) : _.capitalize(currentDef.key);
+    }
+    // Fallback if current theme key somehow not in registry (should not happen with proper setTheme guard)
+    return state.value ? _.capitalize(state.value) : "";
+  });
 
   return {
-    themes: computed(() => registeredThemes.value),
-    current: state,
+    themes: computed(() =>
+      _themeRegistry.value.map((themeDef) => ({
+        key: themeDef.key,
+        name: themeDef.localizationKey ? t(themeDef.localizationKey) : _.capitalize(themeDef.key),
+      })),
+    ),
+    currentThemeKey: state,
+    currentLocalizedName,
     next,
     register,
     unregister,

package/core/composables/useUser/index.ts

@@ -16,11 +16,11 @@ import { RequestPasswordResult } from "./../../types";
 import { createSharedComposable } from "@vueuse/core";
 import { useExternalProvider } from "../../../shared/components/sign-in/useExternalProvider";
 
-interface IUseUser {
+// Interface for the full internal API provided by _createInternalUserLogic
+export interface IUserInternalAPI {
   user: ComputedRef<UserDetail | undefined>;
   loading: ComputedRef<boolean>;
   isAdministrator: ComputedRef<boolean | undefined>;
-  // getAccessToken: () => Promise<string | undefined>;
   loadUser: () => Promise<UserDetail>;
   signIn: (username: string, password: string) => Promise<SignInResult | { succeeded: boolean; error?: any }>;
   signOut: () => Promise<void>;
@@ -32,8 +32,19 @@ interface IUseUser {
   getLoginType: () => Promise<LoginType[]>;
   isAuthenticated: ComputedRef<boolean>;
 }
+
+export interface IAppUserAPI {
+  user: ComputedRef<UserDetail | undefined>;
+  loading: ComputedRef<boolean>;
+  isAuthenticated: ComputedRef<boolean>;
+  isAdministrator: ComputedRef<boolean | undefined>;
+  loadUser: () => Promise<UserDetail>;
+  signOut: () => Promise<void>;
+}
+
 const user: Ref<UserDetail | undefined> = ref();
-function useUserFn(): IUseUser {
+
+export function _createInternalUserLogic(): IUserInternalAPI {
   const loading: Ref<boolean> = ref(false);
 
   const { storage: externalSignInStorage, signOut: externalSignOut } = useExternalProvider();
@@ -72,7 +83,7 @@ function useUserFn(): IUseUser {
     username: string,
     password: string,
   ): Promise<SignInResult | { succeeded: boolean; error?: any; status?: number }> {
-    console.debug(`[@vc-shell/framework#useUser:signIn] - Entry point`);
+    console.debug(`[@vc-shell/framework#_createInternalUserLogic:signIn] - Entry point`);
     try {
       loading.value = true;
       const result = await securityClient.login(new LoginRequest({ userName: username, password }));
@@ -98,7 +109,7 @@ function useUserFn(): IUseUser {
   }
 
   async function signOut(): Promise<void> {
-    console.debug(`[@vc-shell/framework#useUser:signOut] - Entry point`);
+    console.debug(`[@vc-shell/framework#_createInternalUserLogic:signOut] - Entry point`);
 
     user.value = undefined;
 
@@ -110,12 +121,12 @@ function useUserFn(): IUseUser {
   }
 
   async function loadUser(): Promise<UserDetail> {
-    console.debug(`[@vc-shell/framework#useUser:loadUser] - Entry point`);
+    console.debug(`[@vc-shell/framework#_createInternalUserLogic:loadUser] - Entry point`);
 
     try {
       loading.value = true;
       user.value = await securityClient.getCurrentUser();
-      console.log("[useUser]: an user details has been loaded", user.value);
+      console.log("[_createInternalUserLogic]: an user details has been loaded", user.value);
     } catch (e: any) {
       console.error(e);
     } finally {
@@ -187,4 +198,14 @@ function useUserFn(): IUseUser {
   };
 }
 
-export const useUser = createSharedComposable(() => useUserFn());
+export const useUser = createSharedComposable((): IAppUserAPI => {
+  const internals = _createInternalUserLogic();
+  return {
+    user: internals.user,
+    loading: internals.loading,
+    isAuthenticated: internals.isAuthenticated,
+    isAdministrator: internals.isAdministrator,
+    loadUser: internals.loadUser,
+    signOut: internals.signOut,
+  };
+});

package/core/composables/useUserManagement/index.ts

@@ -0,0 +1,45 @@
+import { computed, ComputedRef } from "vue";
+import { createSharedComposable } from "@vueuse/core";
+import { _createInternalUserLogic, IUserInternalAPI } from "../useUser"; // Import the internal logic
+import { SecurityResult, IdentityResult, LoginType, UserDetail, SignInResult } from "./../../api/platform";
+import { RequestPasswordResult } from "./../../types";
+
+// Interface for the API exposed by useUserManagement (for framework/admin use)
+export interface IUserManagementAPI {
+  user: ComputedRef<UserDetail | undefined>;
+  loading: ComputedRef<boolean>;
+  isAdministrator: ComputedRef<boolean | undefined>;
+  isAuthenticated: ComputedRef<boolean>;
+  // Methods specific to user management
+  validateToken: (userId: string, token: string) => Promise<boolean>;
+  validatePassword: (password: string) => Promise<IdentityResult>;
+  resetPasswordByToken: (userId: string, password: string, token: string) => Promise<SecurityResult>;
+  getLoginType: () => Promise<LoginType[]>;
+  loadUser: () => Promise<UserDetail>;
+  requestPasswordReset: (loginOrEmail: string) => Promise<RequestPasswordResult>;
+  changeUserPassword: (oldPassword: string, newPassword: string) => Promise<SecurityResult | undefined>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  signIn: (username: string, password: string) => Promise<SignInResult | { succeeded: boolean; error?: any }>;
+  signOut: () => Promise<void>;
+}
+
+export const useUserManagement = createSharedComposable((): IUserManagementAPI => {
+  // Utilize the same internal logic instance
+  const internals: IUserInternalAPI = _createInternalUserLogic();
+
+  return {
+    user: internals.user,
+    loading: internals.loading,
+    isAdministrator: internals.isAdministrator,
+    isAuthenticated: internals.isAuthenticated,
+    validateToken: internals.validateToken,
+    validatePassword: internals.validatePassword,
+    resetPasswordByToken: internals.resetPasswordByToken,
+    getLoginType: internals.getLoginType,
+    loadUser: internals.loadUser,
+    requestPasswordReset: internals.requestPasswordReset,
+    changeUserPassword: internals.changeUserPassword,
+    signIn: internals.signIn,
+    signOut: internals.signOut,
+  };
+});

package/core/interceptors/index.ts

@@ -1,11 +1,11 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { Router } from "vue-router";
-import { useUser } from "../composables/useUser";
+import { useUserManagement } from "../composables/useUserManagement";
 import { notification } from "../../shared";
 
 export function registerInterceptors(router: Router) {
   const { fetch: originalFetch } = window;
-  const { signOut, isAuthenticated } = useUser();
+  const { signOut, isAuthenticated } = useUserManagement();
 
   window.fetch = async (...args) => {
     /**

package/core/plugins/signalR/index.ts

@@ -2,7 +2,7 @@ import { App, watch, ref, InjectionKey } from "vue";
 import { HubConnection, HubConnectionBuilder, LogLevel } from "@microsoft/signalr";
 import { PushNotification } from "../../api/platform";
 import { useNotifications } from "./../../composables/useNotifications";
-import { useUser } from "../../composables/useUser";
+import { useUserManagement } from "../../composables/useUserManagement";
 import { useCypressSignalRMock } from "cypress-signalr-mock";
 
 const { addNotification } = useNotifications();
@@ -34,7 +34,7 @@ export const signalR = {
     },
   ) {
     currentCreator.value = options?.creator;
-    const { isAuthenticated } = useUser();
+    const { isAuthenticated } = useUserManagement();
     let reconnect = false;
     const connection =
       useCypressSignalRMock("pushNotificationHub", { enableForVitest: true }) ??