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

package/runtime/knowledge/patterns/signalr-notifications.md

@@ -0,0 +1,237 @@
+# SignalR Notifications Pattern
+
+Real-time push notifications from the VirtoCommerce platform to vc-shell modules via SignalR WebSocket transport.
+
+---
+
+## Notification Flow
+
+```
+Platform backend
+  |  (domain event fires)
+  v
+ASP.NET SignalR hub  (/pushNotificationHub)
+  |
+  +-- "Send" channel          (broadcast to all clients)
+  +-- "SendSystemEvents"      (filtered by creator ID)
+  |
+  v
+SignalR plugin (framework auto-installed)
+  |
+  v
+NotificationStore.ingest(message)
+  |
+  +---> history[]              (persistent, loaded from API)
+  +---> realtime[]             (session-only, from SignalR)
+  +---> ToastController        (Level 1: module-level toasts)
+  +---> subscriber callbacks   (Level 2: blade-scoped handlers)
+```
+
+The SignalR plugin connects on login, disconnects on logout, and auto-reconnects on connection loss. Module developers never interact with SignalR directly.
+
+---
+
+## Step 1: Create a Notification Template
+
+Each notification type can have a custom Vue SFC that controls how it renders in the dropdown and toasts. The component receives its data via `useNotificationContext()`, not props.
+
+```vue
+<!-- notifications/OrderShippedEvent.vue -->
+<template>
+  <NotificationTemplate
+    :color="color"
+    :title="notification.title ?? ''"
+    :icon="'lucide-truck'"
+    :notification="notification"
+    @click="onClick"
+  >
+    <VcHint v-if="notification.description" class="tw-mb-1">
+      {{ notification.description }}
+    </VcHint>
+  </NotificationTemplate>
+</template>
+
+<script lang="ts" setup>
+import {
+  NotificationTemplate,
+  useNotificationContext,
+  useBlade,
+} from "@vc-shell/framework";
+import type { PushNotification } from "@vc-shell/framework";
+import { computed } from "vue";
+
+interface IOrderShippedNotification extends PushNotification {
+  orderId?: string;
+  trackingNumber?: string;
+}
+
+const notificationRef = useNotificationContext<IOrderShippedNotification>();
+const notification = computed(() => notificationRef.value);
+
+const color = computed(() =>
+  notification.value.trackingNumber ? "var(--success-400)" : "var(--primary-500)"
+);
+
+const { openBlade } = useBlade();
+
+async function onClick() {
+  await openBlade({ name: "OrderDetails", param: notification.value.orderId });
+}
+</script>
+```
+
+### `NotificationTemplate` props
+
+| Prop           | Type               | Description                                    |
+|----------------|--------------------|------------------------------------------------|
+| `title`        | `string`           | Notification title text                        |
+| `notification` | `PushNotification`  | Full notification object (used for timestamp)  |
+| `icon`         | `string`           | Lucide icon name, e.g. `"lucide-truck"`        |
+| `color`        | `string`           | CSS color/variable for the icon circle         |
+
+The default slot renders below the title/timestamp. Use it for description text, progress bars, or action links.
+
+---
+
+## Step 2: Register in the Module
+
+Pass a `notifications` record to `defineAppModule`. Each key must exactly match the `notifyType` string sent by the platform backend.
+
+```ts
+// modules/orders/index.ts
+import * as pages from "./pages";
+import * as locales from "./locales";
+import { defineAppModule } from "@vc-shell/framework";
+import OrderShippedEvent from "./notifications/OrderShippedEvent.vue";
+
+export default defineAppModule({
+  blades: pages,
+  locales,
+  notifications: {
+    OrderShippedEvent: {
+      template: OrderShippedEvent,
+      toast: { mode: "auto" },
+    },
+  },
+});
+```
+
+### Toast configuration
+
+The `toast` object controls how the notification appears as a popup.
+
+| Property        | Type                                        | Description                                          |
+|-----------------|---------------------------------------------|------------------------------------------------------|
+| `mode`          | `"auto" \| "progress" \| "silent"`          | `auto` = fire-and-forget; `progress` = persistent until complete; `silent` = no toast |
+| `severity`      | `Severity \| (msg) => Severity`             | Static or dynamic: `"info"`, `"warning"`, `"error"`, `"critical"` |
+| `timeout`       | `number`                                    | Override default timeout (ms). Defaults: info=5s, warning=8s, error/critical=persistent |
+| `isComplete`    | `(msg) => boolean`                          | For `"progress"` mode: returns true when the operation finishes |
+| `completedType` | `(msg) => string`                           | For `"progress"` mode: final toast variant (`"success"` or `"error"`) |
+
+#### Toast mode examples
+
+```ts
+// Fire-and-forget toast with default severity (info, 5s timeout)
+toast: { mode: "auto" }
+
+// Warning toast with custom timeout
+toast: { mode: "auto", severity: "warning", timeout: 8000 }
+
+// Long-running operation with progress tracking
+toast: {
+  mode: "progress",
+  severity: (msg) => msg.finished ? "info" : "warning",
+  isComplete: (msg) => !!msg.finished,
+  completedType: (msg) => msg.errorCount ? "error" : "success",
+}
+
+// No toast -- notification only appears in the dropdown
+toast: { mode: "silent" }
+```
+
+### `groupBy` option
+
+For notification types that emit multiple messages for the same logical operation (e.g. export progress updates), set `groupBy` to the field name that identifies the operation. The store upserts instead of appending:
+
+```ts
+notifications: {
+  CatalogExportProgress: {
+    template: ExportProgressTemplate,
+    toast: { mode: "progress", isComplete: (msg) => !!msg.finished },
+    groupBy: "jobId",
+  },
+}
+```
+
+---
+
+## Step 3: React to Notifications in a Blade
+
+Use `useBladeNotifications()` inside `<script setup>` to subscribe to specific notification types. Subscriptions auto-cleanup when the blade unmounts.
+
+```ts
+import { useBladeNotifications } from "@vc-shell/framework";
+
+const { messages, unreadCount, markAsRead } = useBladeNotifications({
+  types: ["OrderShippedEvent"],
+  filter: (msg) => msg.orderId === currentOrderId.value,
+  onMessage: (msg) => {
+    // Refresh blade data when a relevant notification arrives
+    reloadOrder();
+  },
+});
+```
+
+### `useBladeNotifications` API
+
+**Parameters:**
+
+| Field      | Type                        | Description                                      |
+|------------|-----------------------------|--------------------------------------------------|
+| `types`    | `string[]`                  | Notification type(s) to subscribe to             |
+| `filter`   | `(msg) => boolean`          | Optional: further filter by message fields       |
+| `onMessage`| `(msg) => void`             | Callback fired for each matching notification    |
+
+**Returns:**
+
+| Field        | Type                      | Description                                    |
+|--------------|---------------------------|------------------------------------------------|
+| `messages`   | `ComputedRef<T[]>`        | Matching unread messages from the realtime queue |
+| `unreadCount`| `ComputedRef<number>`     | Count of matching unread messages               |
+| `markAsRead` | `(msg) => void`           | Mark a specific message as read                 |
+
+---
+
+## Directory Structure
+
+```
+src/modules/orders/
+├── index.ts                          # defineAppModule with notifications
+├── notifications/
+│   ├── index.ts                      # barrel export
+│   └── OrderShippedEvent.vue         # template component
+└── pages/
+    └── ...
+```
+
+`notifications/index.ts` barrel:
+```ts
+export { default as OrderShippedEvent } from "./OrderShippedEvent.vue";
+```
+
+---
+
+## Key Rules
+
+1. **Notification keys are case-sensitive** -- the key in `notifications: { ... }` must exactly match the `notifyType` string from the platform backend.
+2. **Use `useNotificationContext()`** inside template components, not props. The framework injects the notification via provide/inject.
+3. **Use `useBladeNotifications()`** for blade-level subscriptions (preferred). The deprecated `useNotifications()` still works but logs a warning.
+4. **Do not interact with SignalR directly.** The plugin is auto-installed by the framework. Use the notification store and composables instead.
+5. **`Send` vs `SendSystemEvents`** -- broadcast notifications use the `Send` channel; user-scoped notifications use `SendSystemEvents` filtered by the `creator` field on the server side.
+
+---
+
+## Related Patterns
+
+- [notification-template](./notification-template.md) -- detailed template component authoring guide
+- [module-structure](./module-structure.md) -- overall module layout including notifications directory

package/runtime/vc-app.md

@@ -951,7 +951,29 @@ Parse `DESIGN_PROMPT` into a structured application plan. Apply these parsing ru
 
 **Field extraction:**
 - Concrete field mentions ("subscription token key", "trial period", "email") → columns or formFields with inferred types
-- Type inference: dates → `"date-time"`, booleans/flags → `"boolean"`, numbers/counts/amounts → `"number"`, everything else → `"string"`
+- Type inference — use the most specific type possible:
+
+  | Signal in prompt | Field type | Component (details) | Column type (list) |
+  |---|---|---|---|
+  | date, deadline, birthday, created, expires | `date-time` | `VcDatePicker` | `date-ago` |
+  | is*, has*, can*, enabled, active, published | `boolean` | `VcSwitch` | `status-icon` |
+  | price, cost, amount, total, salary, budget, fee | `currency` | `VcInputCurrency` | `money` |
+  | count, quantity, age, priority (numeric) | `number` | `VcInput type="number"` | `number` |
+  | description, notes, comment, bio, summary | `text` | `VcTextarea` | — (not in list) |
+  | body, content, html, article, template | `rich-text` | `VcEditor` | — (not in list) |
+  | status, state, type, category (from fixed set) | `enum` | `VcSelect` or `VcRadioGroup` | `status` |
+  | tags, labels, categories, roles, permissions | `multi-select` | `VcMultivalue` | — (not in list) |
+  | avatar, logo, photo, thumbnail, banner | `image` | `VcImageUpload` | `image` |
+  | photos, images, screenshots, gallery | `gallery` | `VcGallery` | — (not in list) |
+  | file, attachment, document, contract | `file` | `VcFileUpload` | — (not in list) |
+  | rating, score, stars | `rating` | `VcRating` | — (custom slot) |
+  | color, colour, brandColor | `color` | `VcColorInput` | — (custom slot) |
+  | discount, opacity, percentage, progress | `range` | `VcSlider` | — (custom slot) |
+  | email | `string` | `VcInput` (rules="email") | plain text |
+  | phone, tel | `string` | `VcInput` (type="tel") | plain text |
+  | url, website, link | `string` | `VcInput` (type="url") | plain text |
+  | everything else | `string` | `VcInput` | plain text |
+
 - If a field clearly belongs to a list view (searchable, sortable characteristic) → column
 - If a field clearly belongs to a form (editable, configurable) → formField
 - If unclear → put in both columns and formFields
@@ -976,9 +998,13 @@ DESIGN_PLAN = {
       "name": "string — kebab-case module name (english)",
       "description": "string — what this module does",
       "bladeTypes": "list+details | list-only | details-only",
+      "readOnly": "boolean? — true if details blade is view-only (use VcField instead of VcInput). Default: false",
       "columns": [{ "name": "string", "type": "string", "sortable": true/false }],
-      "formFields": [{ "name": "string", "type": "string", "required": true/false }],
+      "formFields": [{ "name": "string", "type": "string (use specific types from type inference table above)", "required": true/false, "component": "string? — VcInput|VcTextarea|VcEditor|VcDatePicker|VcSelect|VcSwitch|VcCheckbox|VcRadioGroup|VcInputCurrency|VcMultivalue|VcRating|VcSlider|VcColorInput|VcImageUpload|VcGallery|VcFileUpload|VcField", "readOnly": "boolean? — true for display-only fields within editable form" }],
       "toolbarActions": [{ "label": "string", "action": "string (camelCase)" }],
+      "widgets": "string[]? — names of related sub-entities for blade sidebar widgets (e.g., ['offers', 'videos'])",
+      "dashboard": "boolean? — true to generate a DashboardWidgetCard for this module",
+      "notifications": "string[]? — domain event names to generate notification templates for (e.g., ['OrderCreated'])",
       "todos": ["string — exact quote from prompt"]
     }
   ],
@@ -998,8 +1024,18 @@ DESIGN_PLAN = {
 - Entity with both list-worthy columns AND editable fields → `"list+details"`
 - Entity that is mainly a collection/catalog with no edit form → `"list-only"`
 - Entity that is a singleton/settings with no list → `"details-only"`
+- Entity that is view-only (order details, transaction log, audit) → `"list+details"` but mark the details blade `readOnly: true`
 - Default to `"list+details"` when unclear
 
+**Details blade mode inference:**
+- If the entity is view-only (order, transaction, audit log, payment) → set `readOnly: true` on the module — the details generator will use `VcField` for display instead of `VcInput`
+- If the entity has mixed editable + read-only fields → default `readOnly: false`, individual fields marked as `readOnly` in `formFields`
+
+**Feature inference (enrich modules based on prompt signals):**
+- If entity mentions "related" sub-entities (e.g., "product has offers and videos") → add `widgets: ["sub-entity-name"]` — generates blade sidebar widgets with `useBladeWidgets()`
+- If entity is a "primary" concept that would benefit from a dashboard summary → add `dashboard: true` — generates a `DashboardWidgetCard` with stats
+- If entity mentions "notifications" or "events" or "alerts" → add `notifications: ["EventName"]` — generates notification template components
+
 ### Phase 3: Plan Presentation
 
 Present the parsed plan to the user in this format:
@@ -1009,10 +1045,13 @@ Application Plan: {DESIGN_PLAN.appName}
 
 Modules ({count}):
 ─────────────────────────────────────────
-1. {name} ({bladeTypes})
-   Columns: {comma-separated column names}
-   Fields: {comma-separated field names}
+1. {name} ({bladeTypes}{, read-only if readOnly})
+   Columns: {comma-separated column names with types, e.g. "name(string), status(enum), price(currency)"}
+   Fields: {comma-separated "fieldName → Component", e.g. "name → VcInput, description → VcTextarea, price → VcInputCurrency"}
    Actions: {comma-separated action labels}
+   {Widgets: sub-entity-1, sub-entity-2 — if widgets present}
+   {Dashboard: yes — if dashboard present}
+   {Notifications: EventName — if notifications present}
    TODO: "{todo text}"
 
 2. {name} ({bladeTypes})

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`

package/runtime/knowledge/docs/shell/components/app-switcher/app-switcher.docs.md

@@ -1,104 +0,0 @@
-# App Switcher
-
-A component and composable for switching between multiple VirtoCommerce applications (e.g., Vendor Portal, Admin Portal) within the same platform instance.
-
-## Overview
-
-The App Switcher fetches a list of available applications from the platform API and renders them in a dropdown. Clicking an app navigates the browser to that app's URL. Permission checks ensure users only see apps they have access to.
-
-## Directory Structure
-
-```
-app-switcher/
-  components/
-    vc-app-switcher/
-      vc-app-switcher.vue    # Dropdown UI component
-  composables/
-    useAppSwitcher/
-      index.ts               # Data fetching and navigation logic
-```
-
-## Composable: useAppSwitcher
-
-Provides the data layer for app switching.
-
-```typescript
-import { useAppSwitcher } from "@vc-shell/framework";
-
-const { appsList, getApps, switchApp } = useAppSwitcher();
-
-// Fetch available apps on mount
-await getApps();
-
-// Switch to an app (checks permissions, navigates via window.location)
-switchApp(selectedApp);
-```
-
-### Return Value
-
-| Property | Type | Description |
-|---|---|---|
-| `appsList` | `Ref<AppDescriptor[]>` | Reactive list of available applications (readonly computed) |
-| `getApps` | `() => Promise<void>` | Fetches the app list from `AppsClient` |
-| `switchApp` | `(app: AppDescriptor) => void` | Navigates to the app's URL if the user has permission |
-
-### AppDescriptor
-
-Each app in the list has:
-- `id` -- unique identifier
-- `title` -- display name
-- `iconUrl` -- URL of the app icon
-- `relativeUrl` -- the URL path to navigate to
-- `permission` -- required permission string
-
-## Component: VcAppSwitcher
-
-Renders the app list inside a `VcDropdown`. Highlights the currently active app based on URL matching.
-
-### Props
-
-| Prop | Type | Description |
-|---|---|---|
-| `appsList` | `AppDescriptor[]` | List of apps to display |
-
-### Events
-
-| Event | Payload | Description |
-|---|---|---|
-| `onClick` | `AppDescriptor` | Emitted when an app is clicked |
-
-## Usage
-
-```vue
-<script setup>
-import { useAppSwitcher } from "@vc-shell/framework";
-import { VcAppSwitcher } from "@vc-shell/framework";
-
-const { appsList, getApps, switchApp } = useAppSwitcher();
-onMounted(() => getApps());
-</script>
-
-<template>
-  <VcAppSwitcher
-    :apps-list="appsList"
-    @on-click="switchApp"
-  />
-</template>
-```
-
-## Behavior
-
-- `switchApp` checks `hasAccess(app.permission)` before navigating. If access is denied, a notification error is shown.
-- Navigation uses `window.location.href` (full page reload) since apps are separate SPA deployments.
-- The active app is determined by matching `window.location.pathname` against each app's `relativeUrl`.
-
-## Tips
-
-- The composable uses `usePermissions()` internally -- no need to check permissions manually.
-- `getApps()` calls the platform API and may throw on network errors. Wrap in try/catch if needed.
-- The component is typically rendered in the app bar header area.
-
-## Related
-
-- `framework/core/api/platform/` -- `AppsClient` API client
-- `framework/core/composables/usePermissions/` -- permission checking