@vc-shell/vc-app-skill 2.0.0-alpha.24 → 2.0.0-alpha.26

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# [2.0.0-alpha.26](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.25...v2.0.0-alpha.26) (2026-03-25)
+
+**Note:** Version bump only for package @vc-shell/vc-app-skill
+
+# [2.0.0-alpha.25](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.24...v2.0.0-alpha.25) (2026-03-25)
+
+**Note:** Version bump only for package @vc-shell/vc-app-skill
+
 # [2.0.0-alpha.24](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.23...v2.0.0-alpha.24) (2026-03-25)
 
 

package/bin/sync-to-docs.cjs

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Configuration ───────────────────────────────────────────────────────────
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+const FRAMEWORK_DIR = path.join(ROOT, 'framework');
+
+const STORYBOOK_BASE = 'https://vc-shell-storybook.govirto.com';
+
+// Resolve vc-docs path from --docs-path arg or VC_DOCS_PATH env or default
+const docsPathArg = process.argv.find((a) => a.startsWith('--docs-path='));
+const VC_DOCS_PATH =
+  (docsPathArg && docsPathArg.split('=')[1]) ||
+  process.env.VC_DOCS_PATH ||
+  path.resolve(ROOT, '..', 'vc-docs');
+
+const MKDOCS_YML = path.join(VC_DOCS_PATH, 'platform', 'developer-guide', 'mkdocs.yml');
+const DOCS_OUT = path.join(VC_DOCS_PATH, 'platform', 'developer-guide', 'docs', 'custom-apps-development', 'vc-shell');
+
+if (!fs.existsSync(VC_DOCS_PATH)) {
+  console.error(`vc-docs repo not found at: ${VC_DOCS_PATH}`);
+  console.error('Use --docs-path=/path/to/vc-docs or set VC_DOCS_PATH env var');
+  process.exit(1);
+}
+
+// ─── Path mapping ────────────────────────────────────────────────────────────
+// framework relative path → vc-docs relative path (under DOCS_OUT) + nav category
+function mapPath(relPath) {
+  const parts = relPath.replace(/\.docs\.md$/, '').split(path.sep);
+
+  // core/composables/{name}/index → Essentials/composables/{name}.md
+  // core/composables/{name}.docs.md (flat) → Essentials/composables/{name}.md
+  if (parts[0] === 'core' && parts[1] === 'composables') {
+    const name = parts.length >= 3 ? parts[2] : parts[1];
+    return { outPath: `Essentials/composables/${name}.md`, navCategory: 'Composables' };
+  }
+
+  // core/plugins/{name}/* → Essentials/plugins/{name}.md
+  if (parts[0] === 'core' && parts[1] === 'plugins') {
+    const name = parts[2];
+    return { outPath: `Essentials/plugins/${name}.md`, navCategory: 'Plugins' };
+  }
+
+  // core/api/* → Essentials/API-Integration/{name}.md
+  if (parts[0] === 'core' && parts[1] === 'api') {
+    const name = parts[parts.length - 1];
+    return { outPath: `Essentials/API-Integration/${name}.md`, navCategory: null };
+  }
+
+  // core/blade-navigation/* → Essentials/composables/{name}.md
+  if (parts[0] === 'core' && parts[1] === 'blade-navigation') {
+    const name = parts[parts.length - 1];
+    return { outPath: `Essentials/composables/${name}.md`, navCategory: 'Composables' };
+  }
+
+  // core/notifications/* → Essentials/shared/components/notifications.md
+  if (parts[0] === 'core' && parts[1] === 'notifications') {
+    return { outPath: 'Essentials/shared/components/notifications.md', navCategory: null };
+  }
+
+  // ui/components/{tier}/{name}/* → Essentials/ui-components/{name}.md
+  // Skip internal composable docs (table-composables) — only sync the main component doc
+  if (parts[0] === 'ui' && parts[1] === 'components') {
+    const tier = parts[2]; // atoms, molecules, organisms
+    const compDir = parts[3]; // vc-badge, vc-select, etc.
+    const fileName = parts[parts.length - 1];
+    if (compDir) {
+      // Skip sub-directory docs (e.g. composables/table-composables.docs.md) — main doc covers these
+      if (parts.length > 5) return null;
+      // vc-table dir contains VcDataTable — use the actual component name
+      const outName = compDir === 'vc-table' ? 'vc-data-table' : compDir;
+      return { outPath: `Essentials/ui-components/${outName}.md`, navCategory: 'UI Components', tier };
+    }
+  }
+
+  // ui/composables/* → skip (internal table composables)
+  if (parts[0] === 'ui' && parts[1] === 'composables') {
+    return null;
+  }
+
+  // shell/components/{name}/* → Essentials/shared/components/{name}.md
+  if (parts[0] === 'shell' && parts[1] === 'components') {
+    const name = parts[2];
+    return { outPath: `Essentials/shared/components/${name}.md`, navCategory: null };
+  }
+
+  // shell/dashboard/{name}/* → Essentials/shared/components/{name}.md
+  if (parts[0] === 'shell' && parts[1] === 'dashboard') {
+    const name = parts[2];
+    return { outPath: `Essentials/shared/components/${name}.md`, navCategory: null };
+  }
+
+  // Anything else we don't map (core/types, core/utilities, etc.)
+  return null;
+}
+
+// ─── Storybook helpers ───────────────────────────────────────────────────────
+function findStorybookTitle(compDir) {
+  const storiesGlob = fs.readdirSync(compDir).find((f) => f.endsWith('.stories.ts'));
+  if (!storiesGlob) return null;
+
+  const content = fs.readFileSync(path.join(compDir, storiesGlob), 'utf-8');
+  const match = content.match(/title:\s*["']([^"']+)["']/);
+  return match ? match[1] : null;
+}
+
+function storybookTitleToId(title) {
+  // "Data Display/VcBadge" → "data-display-vcbadge"
+  return title
+    .toLowerCase()
+    .replace(/\s+/g, '-')
+    .replace(/\//g, '-');
+}
+
+function buildStorybookSection(title, componentName) {
+  const id = storybookTitleToId(title);
+  const displayName = componentName.split('-').map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join('');
+  return [
+    '',
+    '## Storybook',
+    '',
+    `[${displayName} Storybook](${STORYBOOK_BASE}/?path=/docs/${id}--docs)`,
+    '',
+    '<iframe',
+    `  src="${STORYBOOK_BASE}/iframe.html?id=${id}--docs&viewMode=story&shortcuts=false&singleStory=true"`,
+    '  width="1000"',
+    '  height="500"',
+    '></iframe>',
+    '',
+  ].join('\n');
+}
+
+// ─── Content transformation ──────────────────────────────────────────────────
+function transformContent(content, mapping, frameworkRelPath) {
+  let result = content;
+
+  // If UI component, inject Storybook iframe after first heading
+  if (mapping.navCategory === 'UI Components' && mapping.tier) {
+    const compName = path.basename(mapping.outPath, '.md');
+    const compDir = path.join(FRAMEWORK_DIR, path.dirname(frameworkRelPath));
+    const storybookTitle = findStorybookTitle(compDir);
+
+    if (storybookTitle) {
+      const storySection = buildStorybookSection(storybookTitle, compName);
+      // Insert after first # heading line
+      result = result.replace(/^(# .+\n)/, `$1${storySection}\n`);
+    }
+  }
+
+  return result;
+}
+
+// ─── Find all docs ───────────────────────────────────────────────────────────
+function findDocsFiles(dir, base) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...findDocsFiles(fullPath, base));
+    } else if (entry.name.endsWith('.docs.md')) {
+      results.push(path.relative(base, fullPath));
+    }
+  }
+  return results;
+}
+
+// ─── Nav update helpers ──────────────────────────────────────────────────────
+function extractTitle(content) {
+  const match = content.match(/^# (.+)$/m);
+  return match ? match[1] : null;
+}
+
+function updateNavSection(mkdocsContent, category, entries) {
+  // entries: [{title, path}]
+  // We update the specific nav category section in mkdocs.yml
+  // This is a targeted update — find the category line and replace its children
+
+  const lines = mkdocsContent.split('\n');
+  const result = [];
+  let inCategory = false;
+  let categoryIndent = 0;
+  let replaced = false;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trimStart();
+
+    // Find the category header (e.g., "- Composables:" or "- UI Components:")
+    if (!replaced && trimmed === `- ${category}:`) {
+      categoryIndent = line.length - trimmed.length;
+      inCategory = true;
+      result.push(line);
+
+      // Add all entries with proper indentation
+      const childIndent = ' '.repeat(categoryIndent + 6); // 6 more for child items
+      const sortedEntries = entries.sort((a, b) => a.title.localeCompare(b.title));
+      for (const entry of sortedEntries) {
+        result.push(`${childIndent}- ${entry.title}: ${entry.navPath}`);
+      }
+      replaced = true;
+      continue;
+    }
+
+    // Skip old children of this category
+    if (inCategory) {
+      const lineIndent = line.length - line.trimStart().length;
+      if (line.trim() === '' || lineIndent > categoryIndent) {
+        // Still inside category children, skip
+        if (line.trim().startsWith('-') && lineIndent > categoryIndent) {
+          continue;
+        }
+      }
+      if (line.trim() !== '' && (line.length - line.trimStart().length) <= categoryIndent) {
+        inCategory = false;
+        // This line belongs to next section, keep it
+        result.push(line);
+        continue;
+      }
+      if (line.trim() === '') {
+        continue;
+      }
+      continue;
+    }
+
+    result.push(line);
+  }
+
+  return result.join('\n');
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+const frameworkDocs = findDocsFiles(FRAMEWORK_DIR, FRAMEWORK_DIR);
+
+let synced = 0;
+let skipped = 0;
+let unmapped = 0;
+
+// Track nav entries per category
+const navEntries = {
+  Composables: [],
+  Plugins: [],
+  'UI Components': [],
+};
+
+// Pre-populate nav entries from existing mkdocs.yml to preserve manual entries
+// (we only update categories we manage)
+
+const NAV_PREFIX = 'custom-apps-development/vc-shell/';
+
+for (const relPath of frameworkDocs) {
+  const mapping = mapPath(relPath);
+  if (!mapping) {
+    unmapped++;
+    continue;
+  }
+
+  const src = path.join(FRAMEWORK_DIR, relPath);
+  const dest = path.join(DOCS_OUT, mapping.outPath);
+  const srcContent = fs.readFileSync(src, 'utf-8');
+
+  // Transform content
+  const transformed = transformContent(srcContent, mapping, relPath);
+
+  // Check if dest is identical
+  if (fs.existsSync(dest)) {
+    const destContent = fs.readFileSync(dest, 'utf-8');
+    if (destContent === transformed) {
+      skipped++;
+      // Still collect nav entry
+      if (mapping.navCategory && navEntries[mapping.navCategory]) {
+        const title = extractTitle(srcContent) || path.basename(mapping.outPath, '.md');
+        navEntries[mapping.navCategory].push({
+          title,
+          navPath: NAV_PREFIX + mapping.outPath,
+        });
+      }
+      continue;
+    }
+  }
+
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.writeFileSync(dest, transformed);
+  console.log(`  synced: ${relPath} → ${mapping.outPath}`);
+  synced++;
+
+  // Collect nav entry
+  if (mapping.navCategory && navEntries[mapping.navCategory]) {
+    const title = extractTitle(srcContent) || path.basename(mapping.outPath, '.md');
+    navEntries[mapping.navCategory].push({
+      title,
+      navPath: NAV_PREFIX + mapping.outPath,
+    });
+  }
+}
+
+// Update mkdocs.yml nav sections
+if (fs.existsSync(MKDOCS_YML)) {
+  let mkdocsContent = fs.readFileSync(MKDOCS_YML, 'utf-8');
+  let navUpdated = false;
+
+  for (const [category, entries] of Object.entries(navEntries)) {
+    if (entries.length === 0) continue;
+
+    const before = mkdocsContent;
+    mkdocsContent = updateNavSection(mkdocsContent, category, entries);
+    if (mkdocsContent !== before) navUpdated = true;
+  }
+
+  if (navUpdated) {
+    fs.writeFileSync(MKDOCS_YML, mkdocsContent);
+    console.log(`\n  mkdocs.yml nav updated`);
+  }
+}
+
+// ─── Mark orphaned docs ──────────────────────────────────────────────────────
+// Docs in vc-docs that no longer have a source in framework get a deprecation banner
+const DEPRECATION_BANNER = [
+  '!!! warning "Deprecated"',
+  '    This API has been removed from the current version of the framework.',
+  '    This page is kept for reference only. Do not use in new code.',
+  '',
+].join('\n');
+
+const managedDirs = [
+  path.join(DOCS_OUT, 'Essentials', 'composables'),
+  path.join(DOCS_OUT, 'Essentials', 'plugins'),
+  path.join(DOCS_OUT, 'Essentials', 'ui-components'),
+];
+
+// Build set of all output paths we just synced
+const syncedOutPaths = new Set();
+for (const relPath of frameworkDocs) {
+  const mapping = mapPath(relPath);
+  if (mapping) syncedOutPaths.add(path.join(DOCS_OUT, mapping.outPath));
+}
+
+let deprecated = 0;
+for (const dir of managedDirs) {
+  if (!fs.existsSync(dir)) continue;
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith('.md')) continue;
+    const filePath = path.join(dir, file);
+    if (syncedOutPaths.has(filePath)) continue;
+
+    // File exists in vc-docs but not in framework — mark as deprecated
+    const content = fs.readFileSync(filePath, 'utf-8');
+    if (content.includes('This API has been removed')) continue; // already marked
+
+    fs.writeFileSync(filePath, DEPRECATION_BANNER + '\n' + content);
+    const relFile = path.relative(DOCS_OUT, filePath);
+    console.log(`  deprecated: ${relFile}`);
+    deprecated++;
+  }
+}
+
+console.log(`\nSync to vc-docs complete: ${synced} synced, ${skipped} unchanged, ${unmapped} unmapped, ${deprecated} deprecated`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.0-alpha.24",
+  "version": "2.0.0-alpha.26",
   "description": "AI coding skill for scaffolding and generating VirtoCommerce Shell applications. Works with Claude Code, OpenCode, Gemini, Codex, Cursor.",
   "bin": "./bin/install.cjs",
   "files": [
@@ -20,7 +20,8 @@
   ],
   "scripts": {
     "sync-docs": "node bin/sync-docs.cjs",
-    "knowledge-stats": "node bin/knowledge-stats.cjs"
+    "knowledge-stats": "node bin/knowledge-stats.cjs",
+    "sync-to-docs": "node bin/sync-to-docs.cjs"
   },
   "publishConfig": {
     "access": "public",

package/runtime/VERSION

@@ -1 +1 @@
-2.0.0-alpha.24
+2.0.0-alpha.26

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit c001cdf1a on 2026-03-25T10:46:45.153Z
+Synced from framework at commit 6f3f68723 on 2026-03-25T13:28:17.111Z

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

@@ -1,15 +1,19 @@
-# useBladeWidgets
+# useBladeWidgets / useWidgetTrigger
 
-Declarative headless widget registration for blades. Widgets are automatically registered with the WidgetService on mount and cleaned up on unmount, following the Vue component lifecycle. This composable is the recommended way to add sidebar counter widgets, action buttons, and status indicators to a blade without creating separate Vue component files for each widget.
+Two composables for the widget system — one for the **blade side**, one for the **widget side**.
 
-Headless widgets are defined as plain configuration objects with reactive refs for dynamic values like badge counts and loading states. The WidgetService renders them in the blade sidebar.
+| 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
 
-- Register sidebar widgets (counters, action buttons) for a blade without creating Vue components
-- Refresh widget data programmatically after blade operations (save, delete, status change)
-- Show/hide widgets conditionally based on blade state (e.g., only show after entity is saved)
-- When NOT to use: for widgets that need their own template or complex UI (use a full widget component instead)
+- **`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
 
@@ -70,6 +74,121 @@ refreshAll();
 | `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, IBladeInstance } from "@vc-shell/framework";
+import { markRaw } from "vue";
+import { MessageWidget } from "./components/widgets";
+
+registerExternalWidget({
+  id: "MessageWidget",
+  component: markRaw(MessageWidget),
+  targetBlades: ["ProductDetails", "OrderDetails"],
+  isVisible: (blade?: IBladeInstance) => !!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
@@ -126,10 +245,15 @@ async function save() {
 
 ## 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.
@@ -143,8 +267,39 @@ async function save() {
 - 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` -- expose blade data to widgets
-- `WidgetService` in `@core/services/widget-service`
+- `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/useWidgets/useWidgets.docs.md

@@ -9,7 +9,7 @@ Also exports `provideWidgetService()` for framework-level initialization and `re
 - When you need low-level access to the widget service (register, unregister, query widgets)
 - When building framework infrastructure that manages widget lifecycles
 - When pre-registering widgets from a module's `install()` function before the component tree exists
-- When NOT to use: for typical blade widget work, prefer `useBladeWidgets()` which handles lifecycle automatically. For widget-side logic (badge, refresh), use `useWidget()`.
+- When NOT to use: for typical blade widget work, prefer `useBladeWidgets()` which handles lifecycle automatically. For widget-side logic (badge, refresh), use headless widgets.
 
 ## Quick Start
 
@@ -46,7 +46,7 @@ None.
 | `setActiveWidget` | `(args) => void` | Sets a widget as active with its exposed instance. |
 | `updateActiveWidget` | `() => void` | Triggers the active widget's update function. Deprecated -- use headless widgets instead. |
 | `isWidgetRegistered` | `(id: string) => boolean` | Checks if a widget ID exists in any blade's registry. |
-| `updateWidget` | `(args) => void` | Updates properties of a registered widget (trigger, badge, etc.). Used by `useWidget().setTrigger()`. |
+| `updateWidget` | `(args) => void` | Updates properties of a registered widget (trigger, badge, etc.). |
 | `resolveWidgetProps` | `(widget, bladeData) => Record<string, unknown>` | Resolves widget props from blade data. Deprecated. |
 | `getExternalWidgetsForBlade` | `(bladeId: string) => IExternalWidgetRegistration[]` | Gets external widgets that target a specific blade (registered by other modules). |
 | `getAllExternalWidgets` | `() => IExternalWidgetRegistration[]` | Gets all registered external widgets across all modules. |

package/runtime/knowledge/docs/injection-keys.docs.md

@@ -62,7 +62,7 @@ This centralized approach has several advantages:
 
 | Key | Type | Description |
 |-----|------|-------------|
-| `WidgetIdKey` | `string` | Widget identity (provided by WidgetProvider) |
+| `WidgetScopeKey` | `IWidgetScope` | Widget scope (provided by WidgetContainer for component-based widgets via `WidgetScope.vue`) |
 | `AppRootElementKey` | `Ref<HTMLElement \| undefined>` | App root element for scoped Teleport |
 | `EmbeddedModeKey` | `boolean` | Whether the app runs in embedded mode |
 | `ShellIndicatorsKey` | `ComputedRef<boolean>` | Unread indicator state for sidebar |

package/runtime/knowledge/docs/ui/components/molecules/vc-pagination/vc-pagination.docs.md

@@ -286,5 +286,5 @@ currentPage.value = Math.min(currentPage.value, totalPages.value);
 
 ## Related Components
 
-- [VcDataTable](../../organisms/vc-table/) -- Data table that commonly pairs with pagination for large datasets
+- [VcDataTable](../../organisms/vc-table) -- Data table that commonly pairs with pagination for large datasets
 - [VcSelect](../vc-select/) -- Can be used alongside pagination for a "rows per page" selector

package/runtime/knowledge/docs/ui/components/organisms/{vc-table → vc-data-table}/vc-data-table.docs.md

@@ -24,8 +24,8 @@ Columns are defined as `<VcColumn>` child components -- no configuration objects
 |----------|-----------|
 | Tabular data with sorting, selection, pagination | **VcDataTable** |
 | Simple short list without table features | `v-for` with custom markup |
-| Image/card grid layout | [VcGallery](../vc-gallery/) |
-| Key-value detail display | [VcField](../../molecules/vc-field/) or [VcCard](../../atoms/vc-card/) |
+| Image/card grid layout | [VcGallery](../vc-gallery) |
+| Key-value detail display | [VcField](../../molecules/vc-field) or [VcCard](../../atoms/vc-card) |
 
 Use VcDataTable whenever you need structured rows and columns with any combination of sorting, filtering, inline editing, or column management. **Do not use** VcDataTable for simple lists of 5-10 items that need no table features -- a plain `v-for` loop is lighter. For thumbnail/card grids, prefer VcGallery.
 

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

@@ -1,159 +0,0 @@
-# useWidget
-
-Widget-side composable that auto-discovers widget identity from `WidgetProvider` and provides a `setTrigger()` method to register refresh/badge contracts with the widget service. This composable is the counterpart to the blade-side `useWidgets()` / `useBladeWidgets()` -- while those manage widget registration from the blade's perspective, `useWidget()` is called from inside the widget component itself to communicate its state (badge count, icon, refresh callback) back to the widget system.
-
-**Deprecated**: Prefer headless widgets via `useBladeWidgets()` instead. This composable is only needed for legacy SFC widgets that register trigger contracts manually.
-
-## When to Use
-
-- Inside a widget component wrapped by `WidgetProvider` to register badge counts, refresh callbacks, or click handlers
-- When building a custom blade widget that needs to communicate its state back to the parent blade's widget panel
-- When NOT to use: outside a `WidgetProvider` context (will throw). For managing widgets from the blade side, use `useWidgets()` or `useBladeWidgets()` instead. For new widgets, prefer the headless widget pattern.
-
-## Quick Start
-
-```vue
-<script setup lang="ts">
-import { useWidget } from '@vc-shell/framework';
-import { ref, computed, onMounted } from 'vue';
-
-const { widgetId, setTrigger } = useWidget();
-
-const items = ref<unknown[]>([]);
-const unreadCount = computed(() => items.value.filter((i) => !i.isRead).length);
-
-async function fetchData() {
-  items.value = await api.getWidgetItems();
-}
-
-// Register the trigger contract: badge + refresh callback
-setTrigger({
-  badge: unreadCount,
-  icon: 'fas fa-inbox',
-  title: 'Messages',
-});
-
-onMounted(fetchData);
-</script>
-
-<template>
-  <div class="tw-p-4">
-    <p class="tw-text-sm tw-text-gray-500">Widget ID: {{ widgetId }}</p>
-    <ul>
-      <li v-for="item in items" :key="item.id">{{ item.title }}</li>
-    </ul>
-  </div>
-</template>
-```
-
-## API
-
-### Parameters
-
-None. Identity is auto-discovered from the `WidgetProvider` injection context. The composable injects `WidgetIdKey` for the widget ID, `WidgetServiceKey` for the service, and `BladeDescriptorKey` for the parent blade context.
-
-### Returns
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `widgetId` | `string` | The widget's unique ID, injected by `WidgetProvider`. |
-| `setTrigger` | `(trigger: IWidgetTrigger) => void` | Registers a trigger contract (badge, icon, title, callbacks) for this widget. Can be called multiple times to update the trigger. |
-
-### IWidgetTrigger
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `icon` | `string?` | Lucide or FontAwesome icon name for the widget's display in the dropdown/panel. |
-| `title` | `string?` | Display title for the widget. Falls back to `IWidget.title` if not set. |
-| `badge` | `Ref<number \| string> \| ComputedRef<number \| string>?` | Reactive badge value displayed on the widget button/tab. Pass a computed ref for automatic updates. |
-
-## How It Works
-
-1. **Identity discovery**: On creation, the composable injects `WidgetIdKey` (provided by `WidgetProvider`) and `WidgetServiceKey` (provided by `provideWidgetService()`). It also injects `BladeDescriptorKey` to know which blade this widget belongs to.
-
-2. **Trigger registration**: When you call `setTrigger(trigger)`, the composable calls `widgetService.updateWidget({ id: widgetId, bladeId, widget: { trigger } })`. This stores the trigger contract in the widget service, where the blade's widget panel can read it.
-
-3. **Reactive badges**: Because `badge` accepts a `Ref` or `ComputedRef`, the widget panel automatically updates whenever the badge value changes. There is no need to call `setTrigger` again after the initial registration.
-
-## Recipe: Widget with Live Badge Count
-
-```vue
-<script setup lang="ts">
-import { useWidget } from '@vc-shell/framework';
-import { ref, computed, onMounted } from 'vue';
-
-const { setTrigger } = useWidget();
-const pendingOrders = ref<Order[]>([]);
-
-async function loadPendingOrders() {
-  pendingOrders.value = await orderApi.getPending();
-}
-
-// Badge shows the count of pending orders
-setTrigger({
-  badge: computed(() => pendingOrders.value.length),
-  icon: 'fas fa-clock',
-  title: 'Pending Orders',
-});
-
-onMounted(loadPendingOrders);
-
-// Optionally refresh periodically
-const interval = setInterval(loadPendingOrders, 30_000);
-onUnmounted(() => clearInterval(interval));
-</script>
-
-<template>
-  <div class="tw-space-y-2">
-    <div v-for="order in pendingOrders" :key="order.id" class="tw-p-2 tw-border tw-rounded">
-      <p class="tw-font-medium">{{ order.number }}</p>
-      <p class="tw-text-sm tw-text-gray-500">{{ order.status }}</p>
-    </div>
-    <p v-if="!pendingOrders.length" class="tw-text-gray-400">No pending orders</p>
-  </div>
-</template>
-```
-
-## Recipe: Widget That Updates on Blade Data Change
-
-```vue
-<script setup lang="ts">
-import { useWidget } from '@vc-shell/framework';
-import { inject, watch, ref, computed } from 'vue';
-
-const { setTrigger } = useWidget();
-
-// Inject blade data from parent
-const bladeData = inject('bladeData') as Ref<{ orderId: string }>;
-const comments = ref<Comment[]>([]);
-
-async function loadComments(orderId: string) {
-  comments.value = await commentApi.getByOrder(orderId);
-}
-
-// Reload when blade data changes
-watch(() => bladeData.value.orderId, (id) => {
-  if (id) loadComments(id);
-}, { immediate: true });
-
-setTrigger({
-  badge: computed(() => comments.value.length),
-  icon: 'fas fa-comments',
-  title: 'Comments',
-});
-</script>
-```
-
-## Tips
-
-- **Must be inside `WidgetProvider`.** This composable relies on `WidgetIdKey` being injected by `WidgetProvider`. If called outside that context, it throws an `InjectionError`. The `WidgetProvider` component is automatically rendered by the blade widget system.
-- **`setTrigger` can be called multiple times.** Each call replaces the previous trigger contract. However, since `badge` is reactive, you typically only need to call `setTrigger` once during setup.
-- **Badge accepts both numbers and strings.** You can use `computed(() => 3)` for a numeric badge or `computed(() => '!')` for a text indicator.
-- **Prefer headless widgets for new code.** The `useBladeWidgets()` composable supports a headless pattern where widgets are defined declaratively without a separate SFC. This is simpler and avoids the WidgetProvider ceremony.
-
-## Related
-
-- [useWidgets](../useWidgets/useWidgets.docs.md) -- blade-level widget service access
-- [useBladeWidgets](../useBladeWidgets/) -- lifecycle-managed widget registration for blades (preferred API for new code)
-- `WidgetProvider` -- the component that provides the `WidgetIdKey` injection
-- `framework/injection-keys.ts` -- defines `WidgetIdKey` and `WidgetServiceKey`