@vc-shell/vc-app-skill 2.0.4-pr228.833ff5f → 2.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vc-shell/vc-app-skill",
-  "version": "2.0.4-pr228.833ff5f",
+  "version": "2.0.4",
   "description": "AI coding skill for scaffolding and generating VirtoCommerce Shell applications. Works with Claude Code, OpenCode, Gemini, Codex, Cursor.",
   "bin": "./bin/install.cjs",
   "files": [

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

@@ -0,0 +1,34 @@
+---
+title: usePlatformLocaleSync
+category: composables
+group: user
+---
+
+# usePlatformLocaleSync
+
+One-way reactive bridge from the VirtoCommerce platform's locale storage key (`NG_TRANSLATE_LANG_KEY`, set by AngularJS + angular-translate) to the shell's language service.
+
+Call this composable only when the shell runs embedded inside the platform — `useShellBootstrap` invokes it automatically when `options.isEmbedded === true`. In standalone mode the shell owns its own locale via `VC_LANGUAGE_SETTINGS`, and this composable should not be used.
+
+## When to Use
+
+- Never call directly from feature code. This is a framework-internal sync primitive.
+- It is invoked once per `VcApp` mount from `useShellBootstrap`.
+
+## Behaviour
+
+- Reads `localStorage["NG_TRANSLATE_LANG_KEY"]` via VueUse's `useLocalStorage`, which subscribes to `storage` events for cross-tab reactivity.
+- On setup, if the value is non-empty, calls `LanguageService.setLocale(value)`. `setLocale` normalises the value (e.g. `en-US` → `en-us`), falls back to `en` for unsupported locales, updates `vue-i18n`, reconfigures `vee-validate`, and persists to `VC_LANGUAGE_SETTINGS`.
+- On subsequent changes of the platform key, re-applies the value.
+- Skips empty strings (platform clearing the key does not blank the shell locale).
+- Skips values equal to `currentLocale` to avoid redundant re-configuration.
+
+## How It Works
+
+`useLocalStorage("NG_TRANSLATE_LANG_KEY", "")` returns a `Ref<string>` that VueUse keeps in sync with `localStorage` and the DOM `storage` event (which fires in tabs other than the writer). The composable applies the current ref value once synchronously and then registers a `watch` on it; any cross-tab mutation flows through the ref into `setLocale`.
+
+The watcher is bound to the active effect scope (typically `VcApp`'s setup). When `VcApp` unmounts, the watcher stops; `useLocalStorage` cleans up its own `storage` listener.
+
+## Relationship to `VC_LANGUAGE_SETTINGS`
+
+The sync is strictly one-directional. `setLocale` writes to `VC_LANGUAGE_SETTINGS` as a side effect, but this composable never writes to `NG_TRANSLATE_LANG_KEY`. In embedded mode the in-shell `LanguageSelector` is unreachable (it lives inside `UserDropdownButton`, which is hidden when `isEmbedded` is `true`), so there is no competing writer from the shell side.

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

@@ -0,0 +1,123 @@
+---
+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

@@ -0,0 +1,33 @@
+---
+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.