@vc-shell/framework 1.1.0-alpha.9 → 1.1.1

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## [1.1.1](https://github.com/VirtoCommerce/vc-shell/compare/v1.1.0...v1.1.1) (2025-04-29)
+
+
+
+# [1.1.0](https://github.com/VirtoCommerce/vc-shell/compare/v1.1.0-alpha.2...v1.1.0) (2025-04-29)
+
+
+### Features
+
+* first release ([6685f10](https://github.com/VirtoCommerce/vc-shell/commit/6685f10f98982038206a55b637dc14628a341088))
+* redesign alpha4 wip ([ac48f52](https://github.com/VirtoCommerce/vc-shell/commit/ac48f526f61e85518a238e1e6b49047ff3fcc786))
+* redesign alpha5 ([ac430b8](https://github.com/VirtoCommerce/vc-shell/commit/ac430b80f684d3b920c35778a83c33ec387b2484))
+
+
+
+# [1.1.0-alpha.11](https://github.com/VirtoCommerce/vc-shell/compare/v1.1.0-alpha.2...v1.1.0-alpha.11) (2025-04-29)
+
+
+### Features
+
+* first release ([6685f10](https://github.com/VirtoCommerce/vc-shell/commit/6685f10f98982038206a55b637dc14628a341088))
+* redesign alpha4 wip ([ac48f52](https://github.com/VirtoCommerce/vc-shell/commit/ac48f526f61e85518a238e1e6b49047ff3fcc786))
+* redesign alpha5 ([ac430b8](https://github.com/VirtoCommerce/vc-shell/commit/ac430b80f684d3b920c35778a83c33ec387b2484))
+
+
+
 ## [v1.1.0-alpha.2](https://github.com/VirtoCommerce/vc-shell/compare/v1.0.340...vv1.1.0-alpha.2) (2025-02-25)
 
 

package/core/README.md

@@ -0,0 +1,365 @@
+# VC-Shell Framework Services and Composables Documentation
+
+This document provides an overview of all services and their corresponding composables in the VC-Shell framework.
+
+## Table of Contents
+
+- [VC-Shell Framework Services and Composables Documentation](#vc-shell-framework-services-and-composables-documentation)
+  - [Table of Contents](#table-of-contents)
+  - [Services](#services)
+    - [Widget Service](#widget-service)
+    - [Menu Service](#menu-service)
+    - [Dashboard Service](#dashboard-service)
+    - [App Bar Mobile Buttons Service](#app-bar-mobile-buttons-service)
+    - [Global Search Service](#global-search-service)
+    - [App Bar Menu Service](#app-bar-menu-service)
+    - [Settings Menu Service](#settings-menu-service)
+    - [Toolbar Service](#toolbar-service)
+  - [Composables](#composables)
+    - [useWidgets](#usewidgets)
+    - [useMenuService](#usemenuservice)
+    - [useDashboard](#usedashboard)
+    - [useAppBarMobileButtons](#useappbarmobilebuttons)
+    - [useGlobalSearch](#useglobalsearch)
+    - [useAppBarWidget](#useappbarwidget)
+    - [useSettingsMenu](#usesettingsmenu)
+    - [useToolbar](#usetoolbar)
+
+## Services
+
+### Widget Service
+
+**File:** `/framework/core/services/widget-service.ts`
+
+The Widget Service manages UI components that can be dynamically registered to blades in the application. It provides a central registry for managing widget instances across the application.
+
+**Key Features:**
+- Register and unregister widgets to specific blades
+- Track active widgets
+- Get widgets associated with specific blades
+- Update widget properties
+
+**API:**
+```typescript
+interface IWidgetService {
+  registerWidget: (widget: IWidget, bladeId: string) => void;
+  unregisterWidget: (widgetId: string, bladeId: string) => void;
+  getWidgets: (bladeId: string) => IWidget[];
+  clearBladeWidgets: (bladeId: string) => void;
+  registeredWidgets: IWidgetRegistration[];
+  isActiveWidget: (id: string) => boolean;
+  setActiveWidget: (ref: ComponentInternalInstance["exposed"]) => void;
+  updateActiveWidget: () => void;
+  isWidgetRegistered: (id: string) => boolean;
+  updateWidget: ({ id, bladeId, widget }: { id: string; bladeId: string; widget: Partial<IWidget> }) => void;
+}
+```
+
+### Menu Service
+
+**File:** `/framework/core/services/menu-service.ts`
+
+The Menu Service manages the application's navigation menu structure. It provides functionality for registering, organizing, and retrieving menu items, including support for grouping items and localization.
+
+**Key Features:**
+- Add and remove menu items
+- Automatic grouping of menu items
+- Priority-based ordering
+- Support for localized menu item titles
+- Pre-registration mechanism for items added before service initialization
+
+**API:**
+```typescript
+interface MenuService {
+  addMenuItem: (item: MenuItem) => void;
+  menuItems: Ref<MenuItem[]>;
+  removeMenuItem: (item: MenuItem) => void;
+}
+```
+
+### Dashboard Service
+
+**File:** `/framework/core/services/dashboard-service.ts`
+
+The Dashboard Service manages and organizes dashboard widgets. It provides functionality for registering widgets, updating their positions, and retrieving widgets based on user permissions.
+
+**Key Features:**
+- Register dashboard widgets
+- Retrieve widgets with permission checking
+- Update widget positions
+- Get the layout of dashboard widgets
+
+**API:**
+```typescript
+interface IDashboardService {
+  registerWidget: (widget: DashboardWidget) => void;
+  getWidgets: () => DashboardWidget[];
+  updateWidgetPosition: (widgetId: string, position: DashboardWidgetPosition) => void;
+  getLayout: () => Map<string, DashboardWidgetPosition>;
+}
+```
+
+### App Bar Mobile Buttons Service
+
+**File:** `/framework/core/services/app-bar-mobile-buttons-service.ts`
+
+The App Bar Mobile Buttons Service manages the buttons displayed in the mobile application bar. It provides functionality for registering, organizing, and retrieving these buttons.
+
+**Key Features:**
+- Register and unregister mobile buttons
+- Retrieve buttons with permission checking
+- Support for prioritization and ordering
+
+### Global Search Service
+
+**File:** `/framework/core/services/global-search-service.ts`
+
+The Global Search Service provides a centralized mechanism for searching across the application. It allows registering search providers and executing search operations.
+
+**Key Features:**
+- Register search providers
+- Execute search operations
+- Handle search results
+
+### App Bar Menu Service
+
+**File:** `/framework/core/services/app-bar-menu-service.ts`
+
+The App Bar Menu Service manages the menu items displayed in the application bar. It provides functionality for registering, organizing, and retrieving these menu items.
+
+**Key Features:**
+- Register and manage app bar menu items
+- Support for grouping and organization
+- Priority-based ordering
+
+### Settings Menu Service
+
+**File:** `/framework/core/services/settings-menu-service.ts`
+
+The Settings Menu Service manages the items displayed in the settings menu. It provides functionality for registering, organizing, and retrieving settings menu items.
+
+**Key Features:**
+- Register and manage settings menu items
+- Support for grouping and organization
+- Priority-based ordering
+
+### Toolbar Service
+
+**File:** `/framework/core/services/toolbar-service.ts`
+
+The Toolbar Service manages toolbar items that can be associated with specific blades in the application. It provides functionality for registering, organizing, and accessing blade-specific toolbar actions.
+
+**Key Features:**
+- Register and unregister toolbar items for specific blades
+- Get toolbar items associated with a specific blade
+- Update toolbar item properties dynamically
+- Priority-based ordering of toolbar items
+- Pre-registration mechanism for items added before service initialization
+
+**API:**
+```typescript
+interface IToolbarService {
+  registerToolbarItem: (toolbarItem: IToolbarItem, bladeId: string) => void;
+  unregisterToolbarItem: (toolbarItemId: string, bladeId: string) => void;
+  getToolbarItems: (bladeId: string) => IToolbarItem[];
+  clearBladeToolbarItems: (bladeId: string) => void;
+  registeredToolbarItems: IToolbarRegistration[];
+  isToolbarItemRegistered: (id: string) => boolean;
+  updateToolbarItem: ({
+    id,
+    bladeId,
+    toolbarItem,
+  }: {
+    id: string;
+    bladeId: string;
+    toolbarItem: Partial<IToolbarItem>;
+  }) => void;
+}
+```
+
+## Composables
+
+### useWidgets
+
+**File:** `/framework/core/composables/useWidgets/index.ts`
+
+The useWidgets composable provides access to the Widget Service within Vue components. It also includes functions for providing the Widget Service to child components.
+
+**Key Functions:**
+- `provideWidgetService()`: Creates and provides the Widget Service to the component tree
+- `useWidgets()`: Retrieves the Widget Service instance from the component's injection context
+- `registerWidget()`: Utility function to pre-register widgets before service initialization
+
+**Usage Example:**
+```typescript
+import { useWidgets } from '@vc-shell/framework';
+
+export default {
+  setup() {
+    const widgetService = useWidgets();
+    
+    // Register a widget to a blade
+    widgetService.registerWidget({
+      id: 'my-widget',
+      component: MyWidgetComponent,
+      title: 'My Widget'
+    }, 'blade-id');
+    
+    return { 
+      // Access widget service methods
+      getWidgets: widgetService.getWidgets 
+    };
+  }
+};
+```
+
+### useMenuService
+
+**File:** `/framework/core/composables/useMenuService/index.ts`
+
+The useMenuService composable provides access to the Menu Service within Vue components. It also includes functions for providing the Menu Service to child components.
+
+**Key Functions:**
+- `provideMenuService()`: Creates and provides the Menu Service to the component tree
+- `useMenuService()`: Retrieves the Menu Service instance from the component's injection context
+- `addMenuItem()`: Utility function to pre-register menu items before service initialization
+
+**Usage Example:**
+```typescript
+import { useMenuService } from '@vc-shell/framework';
+
+export default {
+  setup() {
+    const menuService = useMenuService();
+    
+    // Add a menu item
+    menuService.addMenuItem({
+      title: 'New Item',
+      path: '/new-item',
+      priority: 100
+    });
+    
+    return { 
+      menuItems: menuService.menuItems 
+    };
+  }
+};
+```
+
+### useDashboard
+
+**File:** `/framework/core/composables/useDashboard/index.ts`
+
+The useDashboard composable provides access to the Dashboard Service within Vue components. It also includes functions for providing the Dashboard Service to child components.
+
+**Key Functions:**
+- `provideDashboardService()`: Creates and provides the Dashboard Service to the component tree
+- `useDashboard()`: Retrieves the Dashboard Service instance from the component's injection context
+- `registerDashboardWidget()`: Utility function to pre-register dashboard widgets before service initialization
+
+**Usage Example:**
+```typescript
+import { useDashboard } from '@vc-shell/framework';
+
+export default {
+  setup() {
+    const dashboardService = useDashboard();
+    
+    // Register a dashboard widget
+    dashboardService.registerWidget({
+      id: 'sales-widget',
+      name: 'Sales Overview',
+      component: SalesWidgetComponent,
+      size: { width: 2, height: 1 }
+    });
+    
+    return { 
+      widgets: dashboardService.getWidgets() 
+    };
+  }
+};
+```
+
+### useAppBarMobileButtons
+
+**File:** `/framework/core/composables/useAppBarMobileButtons/index.ts`
+
+The useAppBarMobileButtons composable provides access to the App Bar Mobile Buttons Service within Vue components.
+
+**Key Functions:**
+- `provideAppBarMobileButtonsService()`: Creates and provides the service to the component tree
+- `useAppBarMobileButtons()`: Retrieves the service instance from the component's injection context
+
+### useGlobalSearch
+
+**File:** `/framework/core/composables/useGlobalSearch/index.ts`
+
+The useGlobalSearch composable provides access to the Global Search Service within Vue components.
+
+**Key Functions:**
+- `provideGlobalSearchService()`: Creates and provides the service to the component tree
+- `useGlobalSearch()`: Retrieves the service instance from the component's injection context
+
+### useAppBarWidget
+
+**File:** `/framework/core/composables/useAppBarWidget/index.ts`
+
+The useAppBarWidget composable provides functionality for managing widgets in the application bar.
+
+**Key Functions:**
+- Retrieve and manage app bar widgets
+- Register custom app bar widgets
+
+### useSettingsMenu
+
+**File:** `/framework/core/composables/useSettingsMenu/index.ts`
+
+The useSettingsMenu composable provides access to the Settings Menu Service within Vue components.
+
+**Key Functions:**
+- `provideSettingsMenuService()`: Creates and provides the service to the component tree
+- `useSettingsMenu()`: Retrieves the service instance from the component's injection context 
+
+### useToolbar
+
+**File:** `/framework/core/composables/useToolbar.ts`
+
+The useToolbar composable provides access to the Toolbar Service within Vue components, with a focus on blade-specific toolbar actions.
+
+**Key Functions:**
+- `useToolbar()`: Retrieves the Toolbar Service instance, automatically associated with the current blade
+- `registerToolbarItem()`: Registers a toolbar item for the current blade
+- `unregisterToolbarItem()`: Removes a toolbar item from the current blade
+- `updateToolbarItem()`: Updates properties of an existing toolbar item
+- `getToolbarItems()`: Gets all toolbar items for the current blade
+- `clearBladeToolbarItems()`: Removes all toolbar items for the current blade
+
+**Usage Example:**
+```typescript
+import { useToolbar } from '@vc-shell/framework';
+
+export default {
+  setup() {
+    const toolbar = useToolbar();
+    
+    // Register a toolbar item for the current blade
+    toolbar.registerToolbarItem({
+      id: 'save-button',
+      title: 'Save',
+      icon: 'material-save',
+      priority: 100,
+      clickHandler: () => {
+        // Action when clicked
+        saveData();
+      }
+    });
+    
+    // The useToolbar composable automatically cleans up 
+    // items when the component unmounts
+    
+    return {
+      // Other component logic
+    };
+  }
+};
+``` 

package/core/composables/index.ts

@@ -16,3 +16,6 @@ export * from "./useAppInsights";
 export * from "./useTheme";
 export * from "./useWidgets";
 export * from "./useDashboard";
+export * from "./useAppBarWidget";
+export * from "./useSettingsMenu";
+export * from "./useToolbar";

package/core/composables/useAppBarMobileButtons/index.ts

@@ -0,0 +1,17 @@
+import { inject, provide } from "vue";
+import { AppBarMobileButtonsServiceKey } from "../../../injection-keys";
+import { createAppBarMobileButtonsService } from "../../services/app-bar-mobile-buttons-service";
+
+export function provideAppBarMobileButtonsService() {
+  const service = createAppBarMobileButtonsService();
+  provide(AppBarMobileButtonsServiceKey, service);
+  return service;
+}
+
+export function useAppBarMobileButtons() {
+  const service = inject(AppBarMobileButtonsServiceKey);
+  if (!service) {
+    throw new Error("AppBarMobileButtonsService not found");
+  }
+  return service;
+}

package/core/composables/useAppBarWidget/index.ts

@@ -0,0 +1,19 @@
+import { inject, provide } from "vue";
+import { addAppBarWidget, createAppBarWidgetService, IAppBarWidgetService } from "../../services/app-bar-menu-service";
+import { AppBarWidgetServiceKey } from "../../../injection-keys";
+
+export function provideAppBarWidget(): IAppBarWidgetService {
+  const service = createAppBarWidgetService();
+  provide(AppBarWidgetServiceKey, service);
+  return service;
+}
+
+export function useAppBarWidget(): IAppBarWidgetService {
+  const service = inject(AppBarWidgetServiceKey);
+  if (!service) {
+    throw new Error("AppBarWidgetService not found");
+  }
+  return service;
+}
+
+export { addAppBarWidget };

package/core/composables/useGlobalSearch/index.ts

@@ -1,32 +1,9 @@
-import { ref, inject, provide, Ref } from "vue";
+import { inject, provide } from "vue";
 import { GlobalSearchKey } from "../../../injection-keys";
+import { GlobalSearchState, createGlobalSearchService } from "../../services/global-search-service";
 
-export interface GlobalSearchState {
-  isSearchVisible: Ref<Record<string, boolean>>;
-  searchQuery: Ref<Record<string, string>>;
-  toggleSearch: (bladeId: string) => void;
-  setSearchQuery: (bladeId: string, query: string) => void;
-}
-
-export function createGlobalSearch() {
-  const isSearchVisible = ref<Record<string, boolean>>({});
-  const searchQuery = ref<Record<string, string>>({});
-
-  const toggleSearch = (bladeId: string) => {
-    isSearchVisible.value[bladeId] = !isSearchVisible.value[bladeId];
-  };
-
-  const setSearchQuery = (bladeId: string, query: string) => {
-    searchQuery.value[bladeId] = query;
-  };
-
-  const state: GlobalSearchState = {
-    isSearchVisible,
-    searchQuery,
-    toggleSearch,
-    setSearchQuery,
-  };
-
+export function provideGlobalSearch() {
+  const state = createGlobalSearchService();
   provide(GlobalSearchKey, state);
   return state;
 }

package/core/composables/useKeyboardNavigation/index.ts

@@ -0,0 +1,211 @@
+import { onMounted, onBeforeUnmount, ref } from "vue";
+
+interface UseKeyboardNavigationOptions {
+  containerSelector?: string;
+  itemSelector?: string;
+  onEnter?: (element: HTMLElement) => void;
+  onEscape?: () => void;
+  loop?: boolean;
+}
+
+/**
+ * Hook for implementing standard keyboard navigation inside components
+ * @param options Options for configuring navigation
+ * @returns Object with methods for managing focus
+ */
+export function useKeyboardNavigation(options: UseKeyboardNavigationOptions = {}) {
+  const {
+    containerSelector = '[role="menu"]',
+    itemSelector = '[tabindex="0"]',
+    onEnter,
+    onEscape,
+    loop = true,
+  } = options;
+
+  const container = ref<HTMLElement | null>(null);
+  const focusedItemIndex = ref(-1);
+
+  /**
+   * Handler for keydown events for navigation
+   */
+  const handleKeyDown = (event: KeyboardEvent) => {
+    if (!container.value) return;
+
+    const focusableElements = Array.from(container.value.querySelectorAll(itemSelector)) as HTMLElement[];
+
+    if (!focusableElements.length) return;
+
+    switch (event.key) {
+      case "Tab":
+        // Standard tabulation between elements
+        handleTabNavigation(event, focusableElements);
+        break;
+      case "ArrowDown":
+      case "ArrowRight":
+        // Navigation forward
+        event.preventDefault();
+        focusNextElement(focusableElements);
+        break;
+      case "ArrowUp":
+      case "ArrowLeft":
+        // Navigation backward
+        event.preventDefault();
+        focusPreviousElement(focusableElements);
+        break;
+      case "Enter":
+      case " ":
+        // Selection of the current element
+        if (focusedItemIndex.value >= 0 && focusedItemIndex.value < focusableElements.length) {
+          event.preventDefault();
+          if (onEnter) {
+            onEnter(focusableElements[focusedItemIndex.value]);
+          } else {
+            focusableElements[focusedItemIndex.value].click();
+          }
+        }
+        break;
+      case "Escape":
+        // Closing the menu or cancellation
+        if (onEscape) {
+          event.preventDefault();
+          onEscape();
+        }
+        break;
+      case "Home":
+        // Transition to the first element
+        event.preventDefault();
+        focusFirstElement(focusableElements);
+        break;
+      case "End":
+        // Transition to the last element
+        event.preventDefault();
+        focusLastElement(focusableElements);
+        break;
+    }
+  };
+
+  /**
+   * Handling standard tabulation
+   */
+  const handleTabNavigation = (event: KeyboardEvent, elements: HTMLElement[]) => {
+    if (event.shiftKey) {
+      // Shift+Tab - backward
+      focusPreviousElement(elements);
+    } else {
+      // Tab - forward
+      focusNextElement(elements);
+    }
+  };
+
+  /**
+   * Focus on the next element
+   */
+  const focusNextElement = (elements: HTMLElement[]) => {
+    if (!elements.length) return;
+
+    if (focusedItemIndex.value < elements.length - 1) {
+      focusedItemIndex.value++;
+    } else if (loop) {
+      focusedItemIndex.value = 0;
+    }
+
+    elements[focusedItemIndex.value].focus();
+  };
+
+  /**
+   * Focus on the previous element
+   */
+  const focusPreviousElement = (elements: HTMLElement[]) => {
+    if (!elements.length) return;
+
+    if (focusedItemIndex.value > 0) {
+      focusedItemIndex.value--;
+    } else if (loop) {
+      focusedItemIndex.value = elements.length - 1;
+    }
+
+    elements[focusedItemIndex.value].focus();
+  };
+
+  /**
+   * Focus on the first element
+   */
+  const focusFirstElement = (elements: HTMLElement[]) => {
+    if (!elements.length) return;
+    focusedItemIndex.value = 0;
+    elements[0].focus();
+  };
+
+  /**
+   * Focus on the last element
+   */
+  const focusLastElement = (elements: HTMLElement[]) => {
+    if (!elements.length) return;
+    focusedItemIndex.value = elements.length - 1;
+    elements[elements.length - 1].focus();
+  };
+
+  /**
+   * Initialization and event processing
+   */
+  const initKeyboardNavigation = (el: HTMLElement) => {
+    container.value = el;
+    el.addEventListener("keydown", handleKeyDown);
+  };
+
+  /**
+   * Cancelling event processing
+   */
+  const cleanupKeyboardNavigation = () => {
+    if (container.value) {
+      container.value.removeEventListener("keydown", handleKeyDown);
+      container.value = null;
+    }
+  };
+
+  onMounted(() => {
+    if (typeof document !== "undefined" && containerSelector) {
+      const el = document.querySelector(containerSelector) as HTMLElement;
+      if (el) {
+        initKeyboardNavigation(el);
+      }
+    }
+  });
+
+  onBeforeUnmount(() => {
+    cleanupKeyboardNavigation();
+  });
+
+  return {
+    initKeyboardNavigation,
+    cleanupKeyboardNavigation,
+    focusNextElement: () => {
+      if (container.value) {
+        const elements = Array.from(container.value.querySelectorAll(itemSelector)) as HTMLElement[];
+        focusNextElement(elements);
+      }
+    },
+    focusPreviousElement: () => {
+      if (container.value) {
+        const elements = Array.from(container.value.querySelectorAll(itemSelector)) as HTMLElement[];
+        focusPreviousElement(elements);
+      }
+    },
+    focusFirstElement: () => {
+      if (container.value) {
+        const elements = Array.from(container.value.querySelectorAll(itemSelector)) as HTMLElement[];
+        focusFirstElement(elements);
+      }
+    },
+    focusLastElement: () => {
+      if (container.value) {
+        const elements = Array.from(container.value.querySelectorAll(itemSelector)) as HTMLElement[];
+        focusLastElement(elements);
+      }
+    },
+    setFocusedIndex: (index: number) => {
+      focusedItemIndex.value = index;
+    },
+    getFocusedIndex: () => focusedItemIndex.value,
+  };
+}