@vc-shell/vc-app-skill 2.0.0-alpha.25 → 2.0.0-alpha.27

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# [2.0.0-alpha.27](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.26...v2.0.0-alpha.27) (2026-03-25)
+
+**Note:** Version bump only for package @vc-shell/vc-app-skill
+
+# [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

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.25",
+  "version": "2.0.0-alpha.27",
   "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.25
+2.0.0-alpha.27

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 99a2f022b on 2026-03-25T11:57:14.169Z
+Synced from framework at commit 8dddac30c on 2026-03-25T15:16:59.790Z

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-app/vc-app.docs.md

@@ -44,18 +44,20 @@ const user = reactive({ name: "John", role: "Admin" });
 | `name` | `string` | -- | Current user display name. |
 | `role` | `string` | -- | Current user role label. |
 | `disableMenu` | `boolean` | `false` | Hide navigation menu items. |
-| `disableAppSwitcher` | `boolean` | `false` | Hide application switcher UI. |
+| `disableAppHub` | `boolean` | `false` | Hide the Applications section inside the App Hub. |
+| `showSearch` | `boolean` | `false` | Show a search input in the sidebar that filters menu items by title. |
+| `searchPlaceholder` | `string` | `"Search keyword"` | Placeholder text for the sidebar search input. Falls back to i18n key `SHELL.SIDEBAR.SEARCH_PLACEHOLDER`. |
 
 ## Slots
 
 | Slot | Props | Description |
 |------|-------|-------------|
 | `layout` | `{ isMobile, sidebar, appsList, switchApp, openRoot, handleMenuItemClick }` | Override the entire layout (sidebar + navigation). |
-| `menu` | `{ expanded, onItemClick }` | Custom navigation menu. |
+| `menu` | `{ expanded, onItemClick, searchQuery }` | Custom navigation menu. `searchQuery` contains the current search input value (empty string when search is inactive). |
 | `sidebar-header` | `{ logo, expanded, isMobile }` | Custom sidebar header. |
 | `sidebar-footer` | `{ avatar, name, role }` | Custom sidebar footer (user info). |
 | `workspace` | `{ isAuthenticated }` | Override the blade navigation workspace. |
-| `app-switcher` | `{ appsList, switchApp }` | Custom application switcher. |
+| `app-hub` | `{ appsList, switchApp }` | Custom content for the Applications section of the App Hub. |
 
 ## Architecture
 
@@ -72,13 +74,54 @@ VcApp orchestrates several internal systems:
 
 On desktop viewports, VcApp renders a collapsible sidebar on the left with navigation menu items, user info in the footer, and the blade workspace on the right. On mobile viewports, the sidebar is replaced by a top bar with a hamburger menu that opens a slide-over navigation panel.
 
+### Sidebar Menu Search
+
+When `showSearch` is `true`, a search input appears at the top of the sidebar (desktop) or mobile navigation panel. It filters menu items in real time (300ms debounce) by matching the search query against translated item titles:
+
+- **Standalone items** — shown if their title contains the query.
+- **Group items** — if the group title matches, all accessible children are shown. Otherwise, only children whose titles match are displayed.
+- The search query is automatically cleared when a menu item is clicked or when the sidebar collapses.
+
+On desktop, the search input is visible only when the sidebar is expanded (pinned). On mobile, it appears inside the slide-out navigation panel.
+
+If you use the `menu` slot to provide a custom menu, the `searchQuery` prop is passed to your slot so you can implement your own filtering logic.
+
+```vue
+<template>
+  <VcApp :is-ready="true" logo="/logo.svg" title="Admin" show-search search-placeholder="Find a module...">
+    <!-- Default menu with built-in filtering — no extra code needed -->
+  </VcApp>
+</template>
+```
+
+#### Custom Menu with Search
+
+```vue
+<template>
+  <VcApp :is-ready="true" logo="/logo.svg" title="Admin" show-search>
+    <template #menu="{ expanded, onItemClick, searchQuery }">
+      <MyCustomMenu
+        :expanded="expanded"
+        :filter="searchQuery"
+        @select="onItemClick"
+      />
+    </template>
+  </VcApp>
+</template>
+```
+
 ### Dynamic Module Registration
 
 Modules registered via `useDynamicModules()` are loaded at runtime. Each module can contribute menu items, blades, toolbar actions, settings pages, and dashboard widgets. VcApp handles module loading errors gracefully by displaying notification toasts.
 
-### Application Switcher
+### App Hub
+
+The App Hub is a popover panel (desktop) or a swipeable tab (mobile) that combines two sections:
+
+- **Applications** — tile grid of registered apps (e.g., Vendor Portal, Marketplace Admin). Clicking an app switches context without a full page reload. This section can be hidden with `disableAppHub` or customized via the `app-hub` slot. The list is searchable via a built-in search input inside the hub.
+- **Widgets** — registered app bar widgets (notifications, background tasks, etc.). Clicking a widget expands its content inline (desktop) or navigates to its panel (mobile). Widgets are registered via `useAppBarWidget()` and can display badges for unread counts.
 
-When multiple applications are registered (e.g., Vendor Portal, Marketplace Admin), VcApp shows an app switcher in the sidebar header. Users can toggle between apps without a full page reload.
+On desktop, the App Hub opens from the sidebar header menu button (`AppHubPopover`). On mobile, it appears as a second tab ("Hub") in the slide-out navigation panel — users can swipe between Menu and Hub tabs.
 
 ## Recipe: Minimal App Setup
 

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.