@vc-shell/vc-app-skill 2.0.0-alpha.29 → 2.0.0-alpha.31

package/runtime/knowledge/docs/core/composables/useBladeWidgets.docs.md

@@ -1,305 +0,0 @@
-# useBladeWidgets / useWidgetTrigger
-
-Two composables for the widget system — one for the **blade side**, one for the **widget side**.
-
-| Composable | Called from | Purpose |
-|---|---|---|
-| `useBladeWidgets` | Blade component | Register headless widgets + get `refresh()` / `refreshAll()` |
-| `useWidgetTrigger` | External widget component | Register trigger callbacks (`onRefresh`, `onClick`) via provide/inject |
-
-Headless widgets are defined as plain configuration objects with reactive refs for dynamic values like badge counts and loading states. External component-based widgets use `useWidgetTrigger` to register their refresh callbacks so the hosting blade can trigger them.
-
-## When to Use
-
-- **`useBladeWidgets`**: Register sidebar widgets (counters, action buttons) for a blade without creating Vue components. Refresh widget data after blade operations (save, delete).
-- **`useWidgetTrigger`**: Inside an external widget component (registered via `registerExternalWidget`) to register `onRefresh` / `onClick` callbacks. The blade can then call `refresh(widgetId)` or `refreshAll()` to trigger them.
-- When NOT to use `useBladeWidgets`: for widgets that need their own template or complex UI (use `registerExternalWidget` + `useWidgetTrigger` instead).
-
-## Basic Usage
-
-```typescript
-import { useBladeWidgets } from '@vc-shell/framework';
-
-const { refreshAll } = useBladeWidgets([
-  {
-    id: 'OffersWidget',
-    icon: 'lucide-tag',
-    title: 'OFFERS.TITLE',
-    badge: offersCount,
-    loading: offersLoading,
-    onClick: () => openBlade({ name: 'OffersList' }),
-    onRefresh: () => reloadOffers(),
-  },
-  {
-    id: 'ReviewsWidget',
-    icon: 'lucide-star',
-    title: 'REVIEWS.TITLE',
-    badge: reviewsCount,
-    isVisible: computed(() => !!item.value?.id),
-    onClick: () => openBlade({ name: 'ReviewsList' }),
-  },
-]);
-
-// After a save, refresh all widget data
-await saveEntity();
-refreshAll();
-```
-
-## API
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-|---|---|---|---|
-| `widgets` | `HeadlessWidgetDeclaration[]` | Yes | Array of widget declarations |
-
-### HeadlessWidgetDeclaration
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `id` | `string` | Yes | Unique widget identifier |
-| `icon` | `string` | Yes | Icon name (e.g., `"lucide-tag"`) |
-| `title` | `string` | Yes | i18n key or display title |
-| `badge` | `Ref<number \| string>` | No | Badge counter value |
-| `loading` | `Ref<boolean>` | No | Show loading indicator |
-| `disabled` | `Ref<boolean> \| boolean` | No | Disable the widget |
-| `isVisible` | `ComputedRef<boolean> \| boolean` | No | Toggle visibility |
-| `onClick` | `() => void` | No | Action when widget is clicked |
-| `onRefresh` | `() => void \| Promise<void>` | No | Called by `refresh(id)` or `refreshAll()` |
-
-### Returns
-
-| Property | Type | Description |
-|---|---|---|
-| `refresh` | `(widgetId: string) => void` | Trigger `onRefresh` on a specific widget |
-| `refreshAll` | `() => void` | Trigger `onRefresh` on all widgets that have one |
-
-## useWidgetTrigger
-
-Widget-side composable for external component-based widgets. Registers a trigger contract (`onRefresh`, `onClick`, `badge`) via provide/inject — no props, IDs, or service knowledge required.
-
-### Basic Usage
-
-```typescript
-import { useWidgetTrigger } from '@vc-shell/framework';
-
-// Inside an external widget component:
-useWidgetTrigger({ onRefresh: loadData });
-```
-
-### IWidgetTrigger
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `icon` | `string` | No | Lucide icon name for dropdown rendering |
-| `title` | `string` | No | Display title (fallback: widget's title) |
-| `badge` | `Ref<number \| string>` | No | Reactive badge value |
-| `onClick` | `() => void` | No | Handler called when widget is clicked in dropdown |
-| `onRefresh` | `() => void \| Promise<void>` | No | Handler called to refresh widget data |
-| `disabled` | `Ref<boolean> \| boolean` | No | Disabled state |
-
-### How It Works
-
-1. `WidgetContainer` wraps each component-based widget in a `WidgetScope` provider
-2. `WidgetScope` provides a `setTrigger` function scoped to the specific widget ID and blade ID
-3. `useWidgetTrigger` injects this scope and calls `setTrigger` — no props or IDs needed
-4. When the blade calls `refresh(widgetId)` or `refreshAll()`, the registered `onRefresh` is invoked
-
-## Recipe: External Widget with Refresh
-
-A complete example of an external widget that shows an unread message count and supports refresh from the blade:
-
-**1. Register the external widget (module index.ts):**
-
-```typescript
-import { createAppModule, registerExternalWidget, BladeDescriptor } from "@vc-shell/framework";
-import { markRaw } from "vue";
-import { MessageWidget } from "./components/widgets";
-
-registerExternalWidget({
-  id: "MessageWidget",
-  component: markRaw(MessageWidget),
-  targetBlades: ["ProductDetails", "OrderDetails"],
-  isVisible: (blade?: BladeDescriptor) => !!blade?.param,
-});
-```
-
-**2. Widget component (message-widget.vue):**
-
-```vue
-<template>
-  <VcWidget
-    v-loading:500="loading"
-    :title="$t('MESSENGER.WIDGET.TITLE')"
-    icon="lucide-message-circle"
-    :value="messageCount"
-    @click="openMessageBlade"
-  />
-</template>
-
-<script setup lang="ts">
-import { ref, computed, onMounted } from "vue";
-import {
-  loading as vLoading,
-  useBlade,
-  injectBladeContext,
-  useWidgetTrigger,
-  VcWidget,
-} from "@vc-shell/framework";
-
-const ctx = injectBladeContext();
-const entityId = computed(() => (ctx.value.item as { id?: string })?.id ?? "");
-
-const messageCount = ref(0);
-const loading = ref(false);
-
-const loadData = async () => {
-  loading.value = true;
-  try {
-    messageCount.value = await api.getUnreadCount(entityId.value);
-  } finally {
-    loading.value = false;
-  }
-};
-
-// Register refresh callback — blade can call refreshAll() after save
-useWidgetTrigger({ onRefresh: loadData });
-
-onMounted(() => {
-  if (entityId.value) loadData();
-});
-</script>
-```
-
-**3. Blade refreshes widgets after save:**
-
-```vue
-<script setup lang="ts">
-import { useBladeWidgets } from "@vc-shell/framework";
-
-// Empty array — blade doesn't register headless widgets,
-// but gets refresh/refreshAll for external widgets
-const { refresh, refreshAll } = useBladeWidgets([]);
-
-async function save() {
-  await api.saveProduct(product.value);
-  refreshAll();           // refresh all widgets (including MessageWidget)
-  // or: refresh("MessageWidget");  // refresh a specific widget by ID
-}
-</script>
-```
-
-## Recipe: Product Detail Blade with Multiple Widgets
-
-```vue
-<script setup lang="ts">
-import { ref, computed } from "vue";
-import { useBladeWidgets, defineBladeContext } from "@vc-shell/framework";
-
-const product = ref({ id: "prod-1", name: "Widget A" });
-const offersCount = ref(0);
-const reviewsCount = ref(0);
-const offersLoading = ref(false);
-
-// Expose product data to widgets
-defineBladeContext(computed(() => ({ id: product.value?.id })));
-
-async function reloadOffers() {
-  offersLoading.value = true;
-  try {
-    const result = await api.searchOffers({ productId: product.value.id });
-    offersCount.value = result.totalCount;
-  } finally {
-    offersLoading.value = false;
-  }
-}
-
-const { refreshAll } = useBladeWidgets([
-  {
-    id: "OffersWidget",
-    icon: "lucide-tag",
-    title: "PRODUCT.WIDGETS.OFFERS",
-    badge: offersCount,
-    loading: offersLoading,
-    isVisible: computed(() => !!product.value?.id),
-    onClick: () => openBlade({ name: "OffersList" }),
-    onRefresh: reloadOffers,
-  },
-  {
-    id: "ReviewsWidget",
-    icon: "lucide-star",
-    title: "PRODUCT.WIDGETS.REVIEWS",
-    badge: reviewsCount,
-    isVisible: computed(() => !!product.value?.id),
-    onClick: () => openBlade({ name: "ReviewsList" }),
-  },
-]);
-
-async function save() {
-  await api.saveProduct(product.value);
-  // Refresh all widget counts after saving
-  refreshAll();
-}
-</script>
-```
-
-## Prerequisites
-
-**`useBladeWidgets`**:
-- Must be called inside a blade component rendered by `VcBladeSlot` (requires `BladeDescriptorKey` injection).
-- `WidgetService` must be provided in the component tree (automatically available in vc-shell apps).
-- Calling outside a blade context throws an error with a descriptive message.
-
-**`useWidgetTrigger`**:
-- Must be called inside a widget component rendered by `WidgetContainer` (requires `WidgetScopeKey` injection).
-- If called outside a widget scope, logs a warning and does nothing (does not throw).
-
-## Details
-
-- **Lifecycle management**: Widgets are registered in `onMounted` and unregistered in `onUnmounted`. This ensures the WidgetService always reflects the currently visible blades.
-- **Blade ID resolution**: The composable injects `BladeDescriptorKey` to determine which blade the widgets belong to. Each blade has its own isolated widget list.
-- **Trigger pattern**: The `onRefresh` callback is stored as a `trigger` on the registered widget. When `refresh(id)` or `refreshAll()` is called, the trigger is invoked. Widgets without `onRefresh` are silently skipped.
-
-## Tips
-
-- Use `refreshAll()` after any blade operation that might change widget badge counts (save, delete, import).
-- The `badge` field accepts both numbers and strings. Use a string for non-numeric badges like "New" or "!".
-- Keep widget IDs unique within a blade. Duplicate IDs will overwrite previous registrations.
-- Combine with `defineBladeContext` to expose blade entity data that widget components (non-headless) can consume via `injectBladeContext`.
-
-## Common Mistakes
-
-### Calling useWidgetTrigger outside WidgetContainer scope
-
-```typescript
-// Wrong — called in a standalone component, not rendered inside a blade widget slot
-export default defineComponent({
-  setup() {
-    useWidgetTrigger({ onRefresh: loadData }); // ⚠️ Logs warning, trigger not registered
-  },
-});
-```
-
-```typescript
-// Correct — called inside a widget component registered via registerExternalWidget
-// and rendered by WidgetContainer within a blade
-useWidgetTrigger({ onRefresh: loadData }); // ✓ WidgetScope provides context
-```
-
-### Forgetting to pass empty array to useBladeWidgets for refresh-only usage
-
-```typescript
-// Wrong — useBladeWidgets requires an array argument
-const { refreshAll } = useBladeWidgets(); // TS error
-
-// Correct — pass empty array when you only need refresh/refreshAll
-const { refreshAll } = useBladeWidgets([]);
-```
-
-## Related
-
-- `defineBladeContext` / `injectBladeContext` -- expose/consume blade data in external widgets
-- `registerExternalWidget` -- register a component-based widget globally for target blades
-- `WidgetService` in `@core/services/widget-service` -- underlying service
-- `WidgetScope` in `vc-blade/_internal/widgets/WidgetScope.vue` -- provides `WidgetScopeKey` to widget components
-- `VcBladeSlot` -- the blade wrapper that provides `BladeDescriptorKey`

package/runtime/knowledge/docs/core/composables/useGlobalSearch/useGlobalSearch.docs.md

@@ -1,146 +0,0 @@
-# useGlobalSearch
-
-Provides access to the global search service state: per-blade search visibility, search queries, and methods to toggle/close search. The service maintains a map of blade IDs to search state, allowing each blade in the stack to have its own independent search input. The state is shared through Vue's provide/inject system and automatically cleaned up when the scope is disposed.
-
-Also exports `provideGlobalSearch()` for framework-level initialization.
-
-## When to Use
-
-- In blade toolbars or headers to toggle and read the search input visibility for a specific blade
-- To programmatically set or read the search query for a specific blade (e.g., from a URL parameter or external trigger)
-- To integrate search with the blade toolbar's search icon button
-- When NOT to use: for table-level filtering within a blade, use VcDataTable's built-in search header. Global search is for blade-level search that affects the entire blade's content.
-
-## Quick Start
-
-```vue
-<script setup lang="ts">
-import { useGlobalSearch } from '@vc-shell/framework';
-import { computed, watch } from 'vue';
-
-const props = defineProps<{ bladeId: string }>();
-const { isSearchVisible, searchQuery, toggleSearch, setSearchQuery, closeSearch } = useGlobalSearch();
-
-// Reactive accessors scoped to this blade
-const isVisible = computed(() => isSearchVisible.value[props.bladeId] ?? false);
-const query = computed(() => searchQuery.value[props.bladeId] ?? '');
-
-// React to search query changes
-watch(query, (newQuery) => {
-  if (newQuery.length >= 2) {
-    fetchResults(newQuery);
-  }
-});
-
-function onSearchToggle() {
-  toggleSearch(props.bladeId);
-}
-
-function onSearchClose() {
-  closeSearch(props.bladeId);
-}
-</script>
-
-<template>
-  <div>
-    <VcButton icon="fas fa-search" @click="onSearchToggle" />
-    <VcInput
-      v-if="isVisible"
-      :model-value="query"
-      placeholder="Search..."
-      @update:model-value="(val) => setSearchQuery(bladeId, val)"
-      @keydown.escape="onSearchClose"
-    />
-  </div>
-</template>
-```
-
-## API
-
-### Parameters
-
-None.
-
-### Returns (`GlobalSearchState`)
-
-| Property / Method | Type | Description |
-|-------------------|------|-------------|
-| `isSearchVisible` | `Ref<Record<string, boolean>>` | Map of blade IDs to search visibility state. Access via `isSearchVisible.value[bladeId]`. |
-| `searchQuery` | `Ref<Record<string, string>>` | Map of blade IDs to current search query strings. Access via `searchQuery.value[bladeId]`. |
-| `toggleSearch` | `(bladeId: string) => void` | Toggles search visibility for a blade. If visible, hides it (and clears the query). If hidden, shows it. |
-| `setSearchQuery` | `(bladeId: string, query: string) => void` | Sets the search query for a blade. Does not affect visibility. |
-| `closeSearch` | `(bladeId: string) => void` | Hides the search input for a blade and clears the query. |
-
-### Additional Exports
-
-| Export | Description |
-|--------|-------------|
-| `provideGlobalSearch()` | Creates and provides the global search service. Idempotent -- returns existing service if already provided. Cleans up all state on scope disposal. |
-
-## How It Works
-
-The service is a simple reactive state container with two `Ref<Record<string, ...>>` maps. Each blade ID is a key in these maps. This design means:
-
-1. **Blades are isolated**: Each blade has its own search visibility and query. Opening search in one blade does not affect others in the stack.
-2. **Lazy initialization**: A blade's entry in the map is created on first `toggleSearch` or `setSearchQuery` call. Reading a non-existent key returns `undefined`, which the consumer treats as `false`/empty.
-3. **Cleanup**: When `provideGlobalSearch()` scope is disposed (e.g., app unmount), both maps are cleared.
-
-## Recipe: Toolbar Search Button with Badge Indicator
-
-```vue
-<script setup lang="ts">
-import { useGlobalSearch } from '@vc-shell/framework';
-import { computed } from 'vue';
-
-const props = defineProps<{ bladeId: string }>();
-const { isSearchVisible, searchQuery, toggleSearch } = useGlobalSearch();
-
-const hasActiveSearch = computed(() => {
-  const query = searchQuery.value[props.bladeId];
-  return query != null && query.length > 0;
-});
-</script>
-
-<template>
-  <VcButton
-    :icon="hasActiveSearch ? 'fas fa-search-plus' : 'fas fa-search'"
-    :variant="hasActiveSearch ? 'primary' : 'ghost'"
-    @click="toggleSearch(bladeId)"
-  />
-</template>
-```
-
-## Recipe: Pre-Populating Search from URL Query Parameter
-
-```vue
-<script setup lang="ts">
-import { useGlobalSearch } from '@vc-shell/framework';
-import { useRoute } from 'vue-router';
-import { onMounted } from 'vue';
-
-const props = defineProps<{ bladeId: string }>();
-const route = useRoute();
-const { setSearchQuery, toggleSearch } = useGlobalSearch();
-
-onMounted(() => {
-  const urlQuery = route.query.search as string | undefined;
-  if (urlQuery) {
-    setSearchQuery(props.bladeId, urlQuery);
-    toggleSearch(props.bladeId); // make the search input visible
-  }
-});
-</script>
-```
-
-## Tips
-
-- **`toggleSearch` clears the query when hiding.** This is by design -- when the user closes the search, the query is reset. If you need to preserve the query across toggle cycles, store it separately.
-- **Use blade ID, not component instance ID.** The blade ID comes from the blade descriptor and is stable across re-renders. Using a component's `uid` would break if the component is recreated.
-- **State is not persisted.** Unlike sidebar state, search state is in-memory only. Refreshing the page clears all search queries. Use URL query parameters if you need persistence.
-- **Calling outside VcApp throws.** Like all provide/inject composables in the framework, `useGlobalSearch()` throws an `InjectionError` if the service has not been provided.
-
-## Related
-
-- VcDataTable search header -- table-level filtering built into the data table (different from global search)
-- [useToolbar](../useToolbar/) -- toolbar service for blade action buttons (often includes a search toggle button)
-- `framework/core/services/global-search-service.ts` -- underlying service implementation

package/runtime/knowledge/docs/core/composables/useMenuExpanded.docs.md

@@ -1,83 +0,0 @@
-# useMenuExpanded
-
-Manages the sidebar menu expanded/collapsed and hover-expanded state with localStorage persistence. This is the low-level composable that powers the sidebar pin/unpin behavior in the vc-shell admin UI. It tracks two independent states: the permanent "pinned" state (persisted across sessions) and the transient "hover-expanded" state (active only while the user hovers over a collapsed sidebar).
-
-## When to Use
-
-- Low-level control over sidebar pin and hover state
-- Building a custom sidebar component that needs expand/collapse persistence
-- When NOT to use: prefer `useSidebarState` which wraps this composable and adds mobile menu support, derived `isExpanded` computed, and responsive breakpoint handling
-
-## Basic Usage
-
-```typescript
-import { useMenuExpanded } from '@vc-shell/framework';
-
-const { isExpanded, toggleExpanded, isHoverExpanded, toggleHoverExpanded } = useMenuExpanded();
-
-// Toggle pin state (persisted to localStorage)
-toggleExpanded();
-
-// Hover expand with 200ms delay
-toggleHoverExpanded(true);   // opens after delay
-toggleHoverExpanded(false);  // closes immediately
-```
-
-## API
-
-### Returns
-
-| Property | Type | Description |
-|---|---|---|
-| `isExpanded` | `Ref<boolean>` | Pinned state, persisted via `useLocalStorage` |
-| `toggleExpanded` | `() => void` | Toggle the pinned state |
-| `isHoverExpanded` | `Ref<boolean>` | Temporary hover expansion (not persisted) |
-| `toggleHoverExpanded` | `(shouldExpand?: boolean) => void` | Set hover state; opening has a 200ms delay, closing is immediate |
-
-## Recipe: Custom Sidebar with Hover Expand
-
-A common pattern is binding mouse events on the sidebar rail so the menu previews its full width on hover, without permanently pinning it open:
-
-```vue
-<script setup lang="ts">
-import { computed } from "vue";
-import { useMenuExpanded } from "@vc-shell/framework";
-
-const { isExpanded, toggleExpanded, isHoverExpanded, toggleHoverExpanded } = useMenuExpanded();
-
-// The sidebar is visually expanded if pinned OR hover-expanded
-const isVisuallyExpanded = computed(() => isExpanded.value || isHoverExpanded.value);
-</script>
-
-<template>
-  <aside
-    :class="{ 'sidebar--expanded': isVisuallyExpanded }"
-    @mouseenter="toggleHoverExpanded(true)"
-    @mouseleave="toggleHoverExpanded(false)"
-  >
-    <nav>
-      <!-- menu items -->
-    </nav>
-    <button @click="toggleExpanded">
-      {{ isExpanded ? 'Unpin' : 'Pin' }}
-    </button>
-  </aside>
-</template>
-```
-
-## Details
-
-- **Storage key scoping**: The key is scoped per application using the first URL path segment: `VC_APP_MENU_EXPANDED_{appName}`. For example, if the app is hosted at `/vendor-portal/`, the key is `VC_APP_MENU_EXPANDED_vendor-portal`. This allows multiple vc-shell apps on the same domain to maintain independent sidebar states.
-- **Hover delay**: Opening uses a 200ms debounce to prevent accidental expansion when the cursor briefly passes over the sidebar. Closing is immediate to feel responsive.
-- **Cleanup**: Pending hover timeouts are cleaned up via `onScopeDispose` to prevent memory leaks when the composable's effect scope is destroyed.
-- **Default state**: The sidebar starts pinned open (`true`) on first visit, which is the most user-friendly default for new users.
-
-## Tips
-
-- If you call `toggleHoverExpanded(true)` and then `toggleHoverExpanded(false)` within the 200ms window, the expansion is canceled -- the timeout is cleared before it fires.
-- The composable does not handle mobile breakpoints. For responsive behavior, use `useSidebarState` instead, which combines `useMenuExpanded` with mobile detection.
-- Each call to `useMenuExpanded()` creates a new instance with its own timeout tracking, but they share the same localStorage-backed `isExpanded` ref (via `useLocalStorage`). Multiple instances will stay in sync for the pinned state.
-
-## Related
-
-- `useSidebarState` -- higher-level composable that adds mobile menu and derived `isExpanded` computed