npm - @vc-shell/vc-app-skill - Versions diffs - 2.0.11 → 2.1.0-pr248.6401a93 - Mend

@vc-shell/vc-app-skill 2.0.11 → 2.1.0-pr248.6401a93

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/runtime/knowledge/docs/core/notifications/composables/useNotificationContext.docs.md DELETED Viewed

@@ -1,150 +0,0 @@
----
-title: useNotificationContext
-category: composables
-group: notifications
----
-# useNotificationContext
-Reads the current `PushNotification` payload inside a custom notification template. The framework provides the message via Vue's `inject()` from the dropdown or toast surface that hosts the template — the composable returns a reactive `ComputedRef` over it.
-This is the one piece you write when a notification type registered with `defineAppModule({ notifications: { Type: { template } } })` needs a richer rendering than the default `NotificationTemplate` chrome — for example, formatting a domain-specific status, deriving a colored accent, or wiring a click handler that opens the relevant blade.
-## When to use
-- Implementing the `template` component for a notification type registered through `defineAppModule({ notifications })`.
-- Reading typed payload fields (status, entity name, job id) to drive the template's layout, color, or actions.
-- When NOT to use: anywhere outside a notification template. The composable throws if the inject context is not present.
-## Quick Start
-```vue
-<script lang="ts" setup>
-import { PushNotification, NotificationTemplate, useNotificationContext } from "@vc-shell/framework";
-import { computed } from "vue";
-interface IOrderPushNotification extends PushNotification {
-  orderId: string;
-  total: number;
-}
-const notificationRef = useNotificationContext<IOrderPushNotification>();
-const notification = computed(() => notificationRef.value);
-</script>
-<template>
-  <NotificationTemplate
-    :title="notification.title ?? ''"
-    :notification="notification"
-  >
-    <p>Order {{ notification.orderId }} — ${{ notification.total }}</p>
-  </NotificationTemplate>
-</template>
-```
-## API
-### Parameters
-None. The composable is always called without arguments. Generic type parameter narrows the payload shape:
-```typescript
-function useNotificationContext<T extends PushNotification = PushNotification>(): ComputedRef<T>;
-```
-### Returns
-`ComputedRef<T>` — reactive reference to the current `PushNotification` (or your extended subtype via the generic). Update reactively if the same template instance is reused for a refreshed payload (for example, when a progress message is updated through `notification.update`).
-## Common patterns
-### Compute display strings from payload fields
-```vue
-<script lang="ts" setup>
-import { PushNotification, useNotificationContext, NotificationTemplate } from "@vc-shell/framework";
-import { computed } from "vue";
-import { useI18n } from "vue-i18n";
-interface IProductPush extends PushNotification {
-  productName?: string;
-  newStatus?: string;
-}
-const ctx = useNotificationContext<IProductPush>();
-const notification = computed(() => ctx.value);
-const { t } = useI18n({ useScope: "global" });
-const title = computed(() => (notification.value.productName ? `${t("PRODUCTS.PUSH.PRODUCT")} "${notification.value.productName}" ${t("PRODUCTS.PUSH.UPDATE")}` : (notification.value.title ?? "")));
-</script>
-```
-### Open a blade on click
-```vue
-<script lang="ts" setup>
-import { useBlade, useNotificationContext, NotificationTemplate } from "@vc-shell/framework";
-import { computed } from "vue";
-const { openBlade } = useBlade();
-const ctx = useNotificationContext<IOrderPush>();
-const notification = computed(() => ctx.value);
-function onClick() {
-  if (!notification.value.orderId) return;
-  openBlade({ name: "OrderDetails", param: notification.value.orderId });
-}
-</script>
-<template>
-  <NotificationTemplate
-    :title="notification.title ?? ''"
-    :notification="notification"
-    @click="onClick"
-  >
-    <p>{{ notification.description }}</p>
-  </NotificationTemplate>
-</template>
-```
-`NotificationTemplate` re-emits the click event so the host (dropdown row, toast) can close itself before your handler runs.
-### Color the template by status
-```ts
-const notificationStyle = computed(() => {
-  switch (notification.value.newStatus) {
-    case "Approved":
-      return { color: "var(--success-400)", icon: "lucide-check-circle" };
-    case "RequestChanges":
-      return { color: "var(--danger-400)", icon: "lucide-alert-circle" };
-    case "WaitForApproval":
-      return { color: "var(--warning-600)", icon: "lucide-clock" };
-    default:
-      return { color: "var(--primary-400)", icon: "lucide-bell" };
-  }
-});
-```
-`NotificationTemplate` accepts `:color` and `:icon` props that line up with these computeds — the dropdown row and the toast use the same template, so the styling stays consistent across surfaces.
-## Where the template runs
-Notification templates render in two places:
-- **In the bell dropdown**, as one row in the history list.
-- **As a toast**, when the type's `toast.mode` is `"auto"` or `"progress"` (set the mode to `"silent"` to render only in the dropdown).
-The template component must be **the same** in both — register it once on `defineAppModule({ notifications })` and the framework reuses it everywhere.
-## Tips
-- **Always type the generic.** `useNotificationContext<MyPushType>()` enables autocompletion on payload fields. Without it everything degrades to `PushNotification`.
-- **`computed(() => ctx.value)` is idiomatic** in the example apps because consumers want a regular `Ref` shape to pass into child components and template bindings. Direct access via `ctx.value` is fine too.
-- **Do not subscribe inside a template.** The template renders one message; if you need to react to other notifications, do that in a blade with `useBladeNotifications`.
-## Related
-- [useBladeNotifications](./useBladeNotifications.md) — subscribe to types inside a blade.
-- [useNotificationStore](./useNotificationStore.md) — access the underlying store.
-- [Notifications concept page.](../../concepts/notifications.md)

package/runtime/knowledge/docs/core/notifications/composables/useNotificationStore.docs.md DELETED Viewed

@@ -1,113 +0,0 @@
----
-title: useNotificationStore
-category: composables
-group: notifications
----
-# useNotificationStore
-!!! warning "Advanced — most apps do not need this"
-Reach for [useBladeNotifications](./useBladeNotifications.md), [useBroadcastFilter](./useBroadcastFilter.md), and the `notifications` option on `defineAppModule` first. The bell dropdown, unread badge, and toast pipeline are already wired by the shell. This composable is an **escape hatch** for the small set of cases where those facades do not fit.
-Returns the singleton store that backs the framework's notification system. Direct access exposes the full reactive state plus low-level actions: subscribing, ingesting synthetic messages, controlling the broadcast filter, paging history.
-## When to use
-There are only two cases where this composable belongs in app code:
-- **A test or scripted harness** that needs to push synthetic messages through the same pipeline SignalR uses, via `ingest`. Real-time production code never calls `ingest` directly.
-- **A custom shell** that replaces the framework's bell dropdown entirely — typically a module-federation host with its own chrome — and therefore needs to bind to `history`, `unreadCount`, and `markAllAsRead` outside the default surface. Apps that use the standard `VcApp` shell do not need this; the dropdown is already there.
-For everything else — reacting in a blade, gating broadcasts, registering types, displaying a toast — use the facades. Direct store mutations can bypass invariants the facades enforce (broadcast filter, scope-aware cleanup, type validation).
-## Quick Start
-```ts
-import { useNotificationStore } from "@vc-shell/framework";
-const store = useNotificationStore();
-await store.loadHistory(50);
-```
-## API
-The store exposes the full reactive state plus actions. The shape is summarized below; the underlying types live in `core/notifications/store.ts` and `core/notifications/types.ts`.
-| Member                   | Type                                                   | Description                                                                                                                                                                |
-| ------------------------ | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `registry`               | `Map<string, NotificationTypeConfig>`                  | Notification types registered through `defineAppModule({ notifications })`.                                                                                                |
-| `history`                | `Ref<PushNotification[]>`                              | Full history (server-loaded plus ingested), newest first.                                                                                                                  |
-| `realtime`               | `Ref<PushNotification[]>`                              | Session-only realtime queue from the SignalR hub. Drives `messages` in `useBladeNotifications`.                                                                            |
-| `unreadCount`            | `ComputedRef<number>`                                  | Count of unread items in `history`. Drives the bell badge.                                                                                                                 |
-| `hasUnread`              | `ComputedRef<boolean>`                                 | Convenience boolean over `unreadCount`.                                                                                                                                    |
-| `registerType(t, cfg)`   | `(string, NotificationTypeConfig) => void`             | Register a type. Called by the framework when `defineAppModule({ notifications })` runs — rarely needed manually.                                                          |
-| `ingest(msg, opts?)`     | `(PushNotification, { broadcast?: boolean }?) => void` | Push a message through the same pipeline SignalR uses. Broadcasts pass through the active broadcast filter.                                                                |
-| `setBroadcastFilter(fn)` | `((PushNotification) => boolean) => void`              | Install a filter for broadcast messages. Prefer [useBroadcastFilter](./useBroadcastFilter.md) — same method.                                                               |
-| `clearBroadcastFilter()` | `() => void`                                           | Remove the broadcast filter.                                                                                                                                               |
-| `markAsRead(msg)`        | `(PushNotification) => void`                           | Mark one message as read. Mirrors to the server.                                                                                                                           |
-| `markAllAsRead()`        | `() => Promise<void>`                                  | Optimistic mark-all with rollback on failure.                                                                                                                              |
-| `loadHistory(take?)`     | `(number?) => Promise<void>`                           | Fetch history from the platform. Default page size is 10. The shell already calls this at bootstrap.                                                                       |
-| `subscribe(opts)`        | `({ types, filter?, handler? }) => () => void`         | Low-level pub/sub. Returns an `unsub` function. Inside blades use [useBladeNotifications](./useBladeNotifications.md) — it wraps this and registers cleanup automatically. |
-| `getByType(type)`        | `(string) => PushNotification[]`                       | Filter `history` by `notifyType`.                                                                                                                                          |
-## Escape-hatch patterns
-### Manually ingest a message (tests, scripted replay)
-```ts
-const store = useNotificationStore();
-store.ingest({
-  id: "test-1",
-  notifyType: "OrderCreatedDomainEvent",
-  title: "Test order",
-  isNew: true,
-  created: new Date().toISOString(),
-} as PushNotification);
-```
-The ingest pipeline runs the configured toast logic and notifies subscribers exactly like a real SignalR message would, so you can verify the end-to-end behavior of `defineAppModule({ notifications })` + `useBladeNotifications` without a live hub.
-`ingest` with `{ broadcast: true }` simulates `SendSystemEvents` and runs the broadcast filter; without it the message is treated as targeted and bypasses the filter.
-### Custom shell surface (replace the bell dropdown)
-When you are building a shell variant that omits the framework's bell dropdown — for example, a module-federation host that renders its own header — bind to the store directly:
-```ts
-import { useNotificationStore } from "@vc-shell/framework";
-import { onMounted } from "vue";
-const store = useNotificationStore();
-onMounted(() => store.loadHistory(100));
-// Use store.history, store.unreadCount, store.markAllAsRead in your own components.
-```
-If you are using `VcApp` (the default shell), do **not** do this — the dropdown is already mounted and binding to the same store, so a second surface duplicates what is already on screen.
-## Resolution
-`useNotificationStore()` resolves in this order:
-1. If called inside a Vue component's `setup` (or `app.runWithContext()`), it uses `inject(NotificationStoreKey)`.
-2. Otherwise it returns a module-level singleton created on first call.
-The fallback exists so module-federation remotes and standalone scripts see the same store the host app uses.
-## Tips
-- **Prefer facades.** Every time you find yourself writing `store.subscribe(...)` inside a blade, you want `useBladeNotifications`. Every time you write `store.setBroadcastFilter(...)`, you want `useBroadcastFilter`. The facades exist to keep cleanup, typing, and invariants in one place.
-- **Do not iterate `realtime` for unread counts inside a blade.** That is what `useBladeNotifications` does correctly. Touching `realtime` directly couples your component to shell internals.
-- **`loadHistory` replaces, then merges.** Calling it again pages in more entries and merges them with the existing history.
-- **`markAllAsRead` is optimistic.** The local state flips immediately; if the server call fails the change is rolled back and an error toast surfaces.
-- **Direct store mutations can bypass invariants.** The broadcast filter only runs through `ingest({ broadcast: true })`. Pushing arrays around `history.value` directly is not supported.
-## Related
-- [useBladeNotifications](./useBladeNotifications.md) — recommended scope-aware subscription. **Start here.**
-- [useBroadcastFilter](./useBroadcastFilter.md) — broadcast acceptance gate.
-- [useNotificationContext](./useNotificationContext.md) — payload access inside templates.
-- [Notifications concept page.](../../concepts/notifications.md)
-- [Notifications plugin reference.](../../plugins/notifications.md)

package/runtime/knowledge/docs/modules/assets/assets-details.docs.md DELETED Viewed

@@ -1,123 +0,0 @@
----
-title: Assets Module
-category: reference
-group: modules
-slug: assets
----
-# Assets Details Module
-A built-in child blade for editing a single asset's metadata: display name, alt text (images only), and description. Opened by `AssetsManager` when the user clicks a table row, but also usable standalone from any parent blade that needs single-asset editing.
-## Overview
-The blade reads an `AssetLike` instance from `options.asset`, exposes a form pre-populated from it, and delegates persistence back to the caller through two callbacks (`assetEditHandler`, `assetRemoveHandler`). The blade itself never mutates the original asset and never talks to the network — the caller decides what saving and removing means.
-The module is registered as `AssetsDetailsModule` and exposes the `AssetsDetails` blade (registered globally under the name `"AssetsDetails"`).
-## Module Registration
-```typescript
-import { AssetsDetailsModule } from "@vc-shell/framework";
-// Registered automatically when the framework loads
-// Exposes: AssetsDetails blade component
-```
-## Options (via `useBlade`)
-The blade reads its configuration from `options` via `useBlade<AssetsDetailsOptions>()` (not props):
-| Option               | Type                                          | Description                                                                                                                                   |
-| -------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `asset`              | `AssetLike`                                   | The asset to edit. The blade clones it into local state — the source object is never mutated until `assetEditHandler` is called.              |
-| `disabled`           | `boolean?`                                    | When true, every input is read-only and the toolbar Save/Delete buttons are disabled.                                                         |
-| `hiddenFields`       | `string[]?`                                   | Field names to hide. Supported values: `"name"`, `"altText"`, `"description"`. The header (preview, size, created date, URL) is always shown. |
-| `assetEditHandler`   | `(asset: AssetLike) => void \| Promise<void>` | Called by the toolbar Save button with the edited copy. The blade closes itself after the handler resolves.                                   |
-| `assetRemoveHandler` | `(asset: AssetLike) => Promise<void>`         | Called by the toolbar Delete button. The blade closes itself after the handler resolves.                                                      |
-## Usage
-### Direct invocation
-```typescript
-import { useBlade } from "@vc-shell/framework";
-const { openBlade } = useBlade();
-openBlade({
-  name: "AssetsDetails",
-  options: {
-    asset: selectedAsset,
-    disabled: !canEdit.value,
-    hiddenFields: ["altText"],
-    assetEditHandler: async (edited) => {
-      await api.updateAsset(edited);
-    },
-    assetRemoveHandler: async (asset) => {
-      await api.deleteAsset(asset.id);
-    },
-  },
-});
-```
-### Used by AssetsManager
-When `AssetsManager` opens this blade on row click, it wires the manager's mutation methods into the handlers automatically:
-```typescript
-// inside AssetsManager
-openBlade({
-  name: "AssetsDetails",
-  options: {
-    asset,
-    disabled: readonly.value,
-    hiddenFields: options.value?.hiddenFields,
-    assetEditHandler: (asset) => manager.updateItem(asset),
-    assetRemoveHandler: (asset) => manager.remove(asset),
-  },
-});
-```
-## Header
-The header is always rendered above the editable form and is not configurable through `hiddenFields`:
-| Element      | Source                                                                                             |
-| ------------ | -------------------------------------------------------------------------------------------------- |
-| Preview      | `VcImage` thumbnail for image extensions (png/jpg/jpeg/svg/gif), colored extension badge otherwise |
-| Size         | `readableSize(asset.size)` — formatted as `KB`/`MB`/`GB`                                           |
-| Created date | `asset.createdDate` rendered with `type="date-ago"`                                                |
-| URL          | `asset.url` displayed as a copyable link with `asset.name` as the visible label                    |
-## Form fields
-All fields are bound to a local clone of `asset`. They can be hidden individually via `hiddenFields`.
-| Field         | Visibility                                        | Notes                                                                                                                          |
-| ------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `name`        | Hidden if `hiddenFields` includes `"name"`        | Required. Edits the **base name only** — the original extension is preserved on save (e.g. editing `report.pdf` keeps `.pdf`). |
-| `altText`     | Image assets only; hide via `"altText"`           | Plain string. Shown only when `asset.typeId === "Image"`.                                                                      |
-| `description` | Hidden if `hiddenFields` includes `"description"` | Multiline textarea.                                                                                                            |
-## Toolbar
-| Button | Disabled condition                                                                                                  | Action                                                      |
-| ------ | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
-| Save   | `disabled === true`, the form is invalid, or the form is not dirty (vee-validate `useIsFormValid`/`useIsFormDirty`) | `await assetEditHandler(editedAsset)`, then `closeSelf()`   |
-| Delete | `disabled === true`                                                                                                 | `await assetRemoveHandler(editedAsset)`, then `closeSelf()` |
-## Tips
-- **Extension is locked.** The `name` input only edits the base name; the original extension is reattached on save. Renaming `photo.png` to `cover` produces `cover.png`.
-- **Required name validation** uses vee-validate's `required` rule. The Save button stays disabled until validation passes.
-- **`assetEditHandler`** is invoked with the edited clone — the original `options.asset` reference is never mutated. Callers should treat the argument as the new state.
-- **`disabled` makes the blade fully read-only:** inputs are disabled and toolbar Save/Delete are disabled regardless of dirtiness.
-- **`hiddenFields` does not enforce required-ness.** Hiding `"name"` skips the validated `<Field>`, so the Save button only depends on form dirtiness.
-## Related
-- `framework/modules/assets-manager/` -- parent `AssetsManager` blade that opens `AssetsDetails` on row click
-- `framework/core/composables/useAssetsManager/` -- `AssetLike` type definition
-- `framework/core/utilities/assets.ts` -- `isImage`, `readableSize`, `getExtensionColor`, `getExtensionLabel`
-- `framework/ui/components/molecules/vc-field/` -- `VcField` used by the header for size/date/url

package/runtime/knowledge/docs/shell/dashboard/draggable-dashboard/dashboard-widget-skeleton.docs.md DELETED Viewed

@@ -1,33 +0,0 @@
----
-title: DashboardWidgetSkeleton
-category: composables
-group: utilities
-internal: true
----
-# DashboardWidgetSkeleton
-Internal placeholder card used by `GridstackDashboard` while remote modules are still loading. Mimics the shape of `DashboardWidgetCard` (header with icon + title, stats row, content lines) with a shimmer animation. Not exported from `@vc-shell/framework` — consumed only inside the dashboard organism.
-## When to Use
-- You won't use this directly. `GridstackDashboard` renders one per `SkeletonItem` while `ModulesReadyKey` resolves to `false`.
-- If you build a custom dashboard layout and want the same loading aesthetic, copy this file rather than importing it — the component is intentionally internal so the dashboard team can change its markup at any time.
-## Layout Contract
-The skeleton has no props. Its parent positions it via inline `style` (`grid-column` / `grid-row`) inside a 12-column CSS grid. Card height/width is fully determined by the grid cell it occupies, so the skeleton stretches to fill its slot.
-## Accessibility
-- The wrapper has `aria-hidden="true"` so screen readers ignore the visual placeholders. The parent grid carries `role="status"` + `aria-busy="true"` to announce loading state once.
-- Shimmer animation is disabled when the user prefers reduced motion.
-## Design Tokens
-Skeleton inherits dashboard card tokens where possible (`--dashboard-widget-card-background`, `--dashboard-widget-card-border-color`, `--dashboard-widget-card-border-radius`, `--dashboard-widget-card-shadow`) so its silhouette matches the real card. Shimmer colors are read from `--neutrals-100` / `--neutrals-200`.
-## Related
-- [DraggableDashboard](./draggable-dashboard.docs.md) — owns the skeleton grid and decides when to render placeholders.
-- [DashboardWidgetCard](../dashboard-widget-card/dashboard-widget-card.docs.md) — the real card whose shape skeletons imitate.