@vc-shell/framework 1.2.4-beta.8 → 2.0.0-alpha.1

package/core/composables/useFunctions/throttle.ts

@@ -1,13 +0,0 @@
-export default function throttle(func: (...args: unknown[]) => void, delay: number): (...args: unknown[]) => void {
-  let wasThrottled = false;
-
-  return function (...args: unknown[]): void {
-    if (!wasThrottled) {
-      func(...args);
-      wasThrottled = true;
-      setTimeout(() => {
-        wasThrottled = false;
-      }, delay);
-    }
-  };
-}

package/core/composables/useGlobalSearch/index.ts

@@ -1,36 +0,0 @@
-import { inject, provide, getCurrentScope, onScopeDispose } from "vue";
-import { GlobalSearchKey } from "@framework/injection-keys";
-import { GlobalSearchState, createGlobalSearchService } from "@core/services/global-search-service";
-import { createLogger, InjectionError } from "@core/utilities";
-
-const logger = createLogger("use-global-search");
-
-export function provideGlobalSearch(): GlobalSearchState {
-  const existingState = inject(GlobalSearchKey, null);
-  if (existingState) {
-    return existingState;
-  }
-
-  const state = createGlobalSearchService();
-  provide(GlobalSearchKey, state);
-
-  if (getCurrentScope()) {
-    onScopeDispose(() => {
-      state.isSearchVisible.value = {};
-      state.searchQuery.value = {};
-    });
-  }
-
-  return state;
-}
-
-export function useGlobalSearch(): GlobalSearchState {
-  const state = inject<GlobalSearchState>(GlobalSearchKey);
-
-  if (!state) {
-    logger.error("Global search service not found");
-    throw new InjectionError("GlobalSearchService");
-  }
-
-  return state;
-}

package/core/composables/useGlobalSearch/useGlobalSearch.md

@@ -1,263 +0,0 @@
-# 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/useKeyboardNavigation/index.ts

@@ -1,246 +0,0 @@
-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);
-
-  /**
-   * Validate and reset focused index if it's out of bounds
-   */
-  const validateFocusedIndex = (elements: HTMLElement[]) => {
-    if (focusedItemIndex.value >= elements.length || focusedItemIndex.value < 0) {
-      focusedItemIndex.value = elements.length > 0 ? 0 : -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;
-
-    // Validate focused index before processing any navigation
-    validateFocusedIndex(focusableElements);
-
-    switch (event.key) {
-      case "Tab":
-        // Standard tabulation between elements
-        handleTabNavigation(event, focusableElements);
-        break;
-      case "ArrowDown":
-        // Navigation forward
-        event.preventDefault();
-        focusNextElement(focusableElements);
-        break;
-      case "ArrowUp":
-        // Navigation backward
-        event.preventDefault();
-        focusPreviousElement(focusableElements);
-        break;
-      case "Enter":
-      case " ":
-        // Selection of the current element
-        if (focusedItemIndex.value >= 0 && focusedItemIndex.value < focusableElements.length) {
-          const currentElement = focusableElements[focusedItemIndex.value];
-          if (currentElement) {
-            event.preventDefault();
-            if (onEnter) {
-              onEnter(currentElement);
-            } else if (typeof currentElement.click === "function") {
-              currentElement.click();
-            }
-          }
-        }
-        break;
-      case "Escape":
-        // Closing the menu or cancellation
-        if (onEscape) {
-          event.preventDefault();
-          onEscape();
-        }
-        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;
-
-    validateFocusedIndex(elements);
-
-    if (focusedItemIndex.value < elements.length - 1) {
-      focusedItemIndex.value++;
-    } else if (loop) {
-      focusedItemIndex.value = 0;
-    } else {
-      // If loop is false and we're at the last element, stay at the last element
-      return;
-    }
-
-    const elementToFocus = elements[focusedItemIndex.value];
-    if (elementToFocus && typeof elementToFocus.focus === "function") {
-      elementToFocus.focus();
-    }
-  };
-
-  /**
-   * Focus on the previous element
-   */
-  const focusPreviousElement = (elements: HTMLElement[]) => {
-    if (!elements.length) return;
-
-    validateFocusedIndex(elements);
-
-    if (focusedItemIndex.value > 0) {
-      focusedItemIndex.value--;
-    } else if (loop) {
-      focusedItemIndex.value = elements.length - 1;
-    } else {
-      // If loop is false and we're at the first element, stay at the first element
-      return;
-    }
-
-    const elementToFocus = elements[focusedItemIndex.value];
-    if (elementToFocus && typeof elementToFocus.focus === "function") {
-      elementToFocus.focus();
-    }
-  };
-
-  /**
-   * Focus on the first element
-   */
-  const focusFirstElement = (elements: HTMLElement[]) => {
-    if (!elements.length) return;
-    focusedItemIndex.value = 0;
-    const elementToFocus = elements[0];
-    if (elementToFocus && typeof elementToFocus.focus === "function") {
-      elementToFocus.focus();
-    }
-  };
-
-  /**
-   * Focus on the last element
-   */
-  const focusLastElement = (elements: HTMLElement[]) => {
-    if (!elements.length) return;
-    focusedItemIndex.value = elements.length - 1;
-    const elementToFocus = elements[elements.length - 1];
-    if (elementToFocus && typeof elementToFocus.focus === "function") {
-      elementToFocus.focus();
-    }
-  };
-
-  /**
-   * Initialization and event processing
-   */
-  const initKeyboardNavigation = (el: HTMLElement) => {
-    // Clean up previous listener to avoid double-registration
-    // (onMounted may have auto-attached to a global containerSelector match)
-    if (container.value) {
-      container.value.removeEventListener("keydown", handleKeyDown);
-    }
-    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) => {
-      if (container.value) {
-        const elements = Array.from(container.value.querySelectorAll(itemSelector)) as HTMLElement[];
-        if (index >= 0 && index < elements.length) {
-          focusedItemIndex.value = index;
-        }
-      }
-    },
-    getFocusedIndex: () => focusedItemIndex.value,
-  };
-}

package/core/composables/useLanguages/index.ts

@@ -1,48 +0,0 @@
-import { hasInjectionContext, inject, provide } from "vue";
-import { LanguageServiceKey } from "@framework/injection-keys";
-import { ILanguageService, createLanguageService } from "@core/services/language-service";
-import { createLogger, InjectionError } from "@core/utilities";
-
-const logger = createLogger("use-languages");
-let fallbackLanguageService: ILanguageService | null = null;
-
-export interface IUseLanguages extends ILanguageService {}
-
-function getOrCreateFallbackLanguageService(): ILanguageService {
-  if (!fallbackLanguageService) {
-    fallbackLanguageService = createLanguageService();
-  }
-
-  return fallbackLanguageService;
-}
-
-export function provideLanguages(): ILanguageService {
-  if (!hasInjectionContext()) {
-    logger.warn("No injection context for provideLanguages; using fallback language service");
-    return getOrCreateFallbackLanguageService();
-  }
-
-  const existingService = inject(LanguageServiceKey, null);
-  if (existingService) {
-    return existingService;
-  }
-
-  const service = createLanguageService();
-  provide(LanguageServiceKey, service);
-  return service;
-}
-
-export function useLanguages(): IUseLanguages {
-  if (!hasInjectionContext()) {
-    return getOrCreateFallbackLanguageService();
-  }
-
-  const languageService = inject(LanguageServiceKey, null);
-
-  if (!languageService) {
-    logger.error("Language service not found");
-    throw new InjectionError("LanguageService");
-  }
-
-  return languageService;
-}

package/core/composables/useLoading/index.ts

@@ -1,9 +0,0 @@
-import { computed, ComputedRef, Ref } from "vue";
-
-export interface HasLoading {
-  loading: Readonly<Ref<boolean>>;
-}
-
-export function useLoading(...args: Readonly<Ref<boolean>>[]): ComputedRef<boolean> {
-  return computed(() => args.some((item) => item.value));
-}

package/core/composables/useMenuService/index.test.ts

@@ -1,86 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { defineComponent, h, inject } from "vue";
-import { mount } from "@vue/test-utils";
-import { MenuServiceKey } from "@framework/injection-keys";
-import { provideMenuService, useMenuService } from "@core/composables/useMenuService";
-import { createMenuService } from "@core/services/menu-service";
-
-describe("useMenuService", () => {
-  it("throws InjectionError when no service is provided", () => {
-    const TestComp = defineComponent({
-      setup() {
-        expect(() => useMenuService()).toThrow("MenuService");
-        return () => h("div");
-      },
-    });
-
-    mount(TestComp);
-  });
-
-  it("returns injected service", () => {
-    const service = createMenuService();
-
-    const TestComp = defineComponent({
-      setup() {
-        const result = useMenuService();
-        expect(result).toBe(service);
-        return () => h("div");
-      },
-    });
-
-    mount(TestComp, {
-      global: {
-        provide: { [MenuServiceKey as symbol]: service },
-      },
-    });
-  });
-});
-
-describe("provideMenuService", () => {
-  it("creates and provides a service", () => {
-    let providedService: any;
-    let injectedService: any;
-
-    const Parent = defineComponent({
-      setup() {
-        providedService = provideMenuService();
-        return () => h(Child);
-      },
-    });
-
-    const Child = defineComponent({
-      setup() {
-        injectedService = inject(MenuServiceKey);
-        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 = provideMenuService();
-        return () => h(Parent);
-      },
-    });
-
-    const Parent = defineComponent({
-      setup() {
-        secondResult = provideMenuService();
-        return () => h("div");
-      },
-    });
-
-    mount(GrandParent);
-
-    expect(firstResult).toBe(secondResult);
-  });
-});