@vc-shell/vc-app-skill 2.1.0-pr255.87acc71 → 2.1.0-pr256.0fe3abb

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

@@ -19,7 +19,7 @@ Columns are defined as `<VcColumn>` child components -- no configuration objects
 
 **Key facts:**
 
-- 82 Storybook stories covering every feature permutation
+- 90 Storybook stories covering every feature permutation
 - Automatic mobile card view on small screens
 - State persistence (column widths, order, sort, filters) to localStorage/sessionStorage
 - Full TypeScript generics -- `VcDataTable<Product>` propagates types to events and slots
@@ -266,10 +266,10 @@ Clicking a sortable column header cycles: unsorted -> ascending -> descending.
 
 ### Removable Sort
 
-Allow users to remove sorting entirely (3-state cycle: asc -> desc -> none):
+Enabled by default: the sort cycle is 3-state (asc -> desc -> none), so users can remove sorting entirely. Set `:removable-sort="false"` to force the 2-state cycle (asc -> desc):
 
 ```vue
-<VcDataTable :items="products" :removable-sort="true">
+<VcDataTable :items="products" :removable-sort="false">
   <VcColumn id="name" field="name" title="Name" sortable />
 </VcDataTable>
 ```
@@ -1109,8 +1109,14 @@ async function load() {
   });
 }
 
+// The initial load reads the values already restored from the URL.
 onMounted(() => load());
-watch(sortExpression, () => load());
+
+// Reset to page 1 when the search changes, BEFORE the reload watcher fires.
+watch(searchValue, () => pagination.setPage(1));
+
+// Reload whenever any query dimension changes.
+watch([sortExpression, searchValue, () => pagination.skip], () => load());
 </script>
 
 <template>
@@ -1140,6 +1146,12 @@ watch(sortExpression, () => load());
 
 The `state-key` on `VcDataTable` here persists column layout to localStorage; the `stateKey` passed to the composables persists query state to the URL. Both use the same string value but serve different purposes.
 
+!!! warning "Reset the page to 1 when the search changes"
+`watch(searchValue, () => pagination.setPage(1))` is required, not optional. Without it, searching while on a later page leaves a stale `<stateKey>_page` in the URL. On the next reload the list requests that page of the **filtered** result set — `skip` overshoots the (smaller) result count and the table renders an empty "nothing found" state even though matches exist on page 1. Resetting to page 1 drops `_page` from the URL and keeps the `(search, page)` pair consistent. Apply the same reset whenever a filter changes.
+
+!!! tip "Composable-owned pagination"
+When `useDataTablePagination` lives inside a list composable (so `onPageChange` can drive the fetch), thread the `stateKey` through as a composable option (`useOffersList({ stateKey })`) instead of hard-coding it — the blade still owns the key. Make sure the **initial** load passes `skip: pagination.skip` so a restored page is applied on first paint.
+
 ---
 
 ## Row Actions
@@ -1365,38 +1377,39 @@ function onRowRemove(event: { data: Product; index: number; cancel: () => void }
 
 ### Props
 
-| Prop                | Type                                        | Default         | Description                                                                                                                                                  |
-| ------------------- | ------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `id`                | `string`                                    | **required**    | Unique column identifier. Must be unique within the table.                                                                                                   |
-| `field`             | `string`                                    | same as `id`    | Data field path to read from each row item.                                                                                                                  |
-| `title`             | `string`                                    | --              | Header text displayed in the column header.                                                                                                                  |
-| `type`              | `CellType`                                  | `"text"`        | Cell formatter: `"text"`, `"number"`, `"money"`, `"date"`, `"datetime"`, `"date-ago"`, `"time"`, `"image"`, `"link"`, `"html"`, `"status"`, `"status-icon"`. |
-| `currencyField`     | `string`                                    | `"currency"`    | Field to read currency code from (for `type="money"`).                                                                                                       |
-| `format`            | `string`                                    | --              | Date/number format string (e.g. `"DD.MM.YYYY"`).                                                                                                             |
-| `width`             | `string \| number`                          | --              | Column width in px or CSS value (e.g. `200`, `"150px"`).                                                                                                     |
-| `minWidth`          | `string \| number`                          | `60`            | Minimum column width during resize.                                                                                                                          |
-| `maxWidth`          | `string \| number`                          | --              | Maximum column width during resize.                                                                                                                          |
-| `align`             | `"start" \| "center" \| "end"`              | --              | Cell text alignment.                                                                                                                                         |
-| `headerAlign`       | `"start" \| "center" \| "end"`              | same as `align` | Header text alignment.                                                                                                                                       |
-| `sortable`          | `boolean`                                   | `false`         | Enable sorting on this column.                                                                                                                               |
-| `sortField`         | `string`                                    | same as `id`    | Backend field name used in sort events.                                                                                                                      |
-| `filter`            | `ColumnFilterConfig`                        | --              | Filter config: `true` (text), `"field"` (text with custom field), `{ options }` (select), `{ range }` (date range).                                          |
-| `filterField`       | `string`                                    | same as `id`    | Backend field name used in filter events.                                                                                                                    |
-| `filterPlaceholder` | `string`                                    | --              | Placeholder text for the filter input.                                                                                                                       |
-| `visible`           | `boolean`                                   | `true`          | Initial visibility. Hidden columns can be toggled via column switcher.                                                                                       |
-| `alwaysVisible`     | `boolean`                                   | `false`         | Keep visible when `showAllColumns=false` (blade narrows).                                                                                                    |
-| `editable`          | `boolean`                                   | `false`         | Enable inline editing for this column's cells.                                                                                                               |
-| `rules`             | `Record<string, unknown>`                   | --              | Validation rules for the editable cell.                                                                                                                      |
-| `class`             | `string`                                    | --              | CSS class applied to header and body cells.                                                                                                                  |
-| `headerClass`       | `string`                                    | --              | CSS class applied only to the header cell.                                                                                                                   |
-| `bodyClass`         | `string`                                    | --              | CSS class applied only to body cells.                                                                                                                        |
-| `lineClamp`         | `number`                                    | `2`             | Max lines to display before truncating. `0` = no clamp.                                                                                                      |
-| `selectionMode`     | `"single" \| "multiple"`                    | --              | Renders a selection checkbox/radio column.                                                                                                                   |
-| `rowEditor`         | `boolean`                                   | `false`         | Renders save/cancel buttons for row edit mode.                                                                                                               |
-| `rowReorder`        | `boolean`                                   | `false`         | Renders a drag handle for row reordering.                                                                                                                    |
-| `expander`          | `boolean`                                   | `false`         | Renders an expand/collapse toggle.                                                                                                                           |
-| `mobileRole`        | `"title" \| "image" \| "field" \| "status"` | --              | Role in mobile card layout.                                                                                                                                  |
-| `mobileVisible`     | `boolean`                                   | `false`         | Whether column is visible on mobile (hidden unless `mobileRole` set).                                                                                        |
+| Prop                | Type                                                           | Default         | Description                                                                                                                                                  |
+| ------------------- | -------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`                | `string`                                                       | **required**    | Unique column identifier. Must be unique within the table.                                                                                                   |
+| `field`             | `string`                                                       | same as `id`    | Data field path to read from each row item.                                                                                                                  |
+| `title`             | `string`                                                       | --              | Header text displayed in the column header.                                                                                                                  |
+| `type`              | `CellType`                                                     | `"text"`        | Cell formatter: `"text"`, `"number"`, `"money"`, `"date"`, `"datetime"`, `"date-ago"`, `"time"`, `"image"`, `"link"`, `"html"`, `"status"`, `"status-icon"`. |
+| `currencyField`     | `string`                                                       | `"currency"`    | Field to read currency code from (for `type="money"`).                                                                                                       |
+| `format`            | `string`                                                       | --              | Date/number format string (e.g. `"DD.MM.YYYY"`).                                                                                                             |
+| `width`             | `string \| number`                                             | --              | Column width in px or CSS value (e.g. `200`, `"150px"`).                                                                                                     |
+| `minWidth`          | `string \| number`                                             | --              | Minimum column width during resize. When unset, the engine applies a 40px minimum.                                                                           |
+| `maxWidth`          | `string \| number`                                             | --              | Maximum column width during resize.                                                                                                                          |
+| `align`             | `"start" \| "center" \| "end"`                                 | --              | Cell text alignment.                                                                                                                                         |
+| `headerAlign`       | `"start" \| "center" \| "end"`                                 | same as `align` | Header text alignment.                                                                                                                                       |
+| `sortable`          | `boolean`                                                      | `false`         | Enable sorting on this column.                                                                                                                               |
+| `sortField`         | `string`                                                       | same as `id`    | Backend field name used in sort events.                                                                                                                      |
+| `filter`            | `ColumnFilterConfig`                                           | --              | Filter config: `true` (text), `"field"` (text with custom field), `{ options }` (select), `{ range }` (date range).                                          |
+| `filterField`       | `string`                                                       | same as `id`    | Backend field name used in filter events.                                                                                                                    |
+| `filterPlaceholder` | `string`                                                       | --              | Placeholder text for the filter input.                                                                                                                       |
+| `visible`           | `boolean`                                                      | `true`          | Initial visibility. Hidden columns can be toggled via column switcher.                                                                                       |
+| `alwaysVisible`     | `boolean`                                                      | `false`         | Keep visible when `showAllColumns=false` (blade narrows).                                                                                                    |
+| `editable`          | `boolean`                                                      | `false`         | Enable inline editing for this column's cells.                                                                                                               |
+| `rules`             | `Record<string, unknown>`                                      | --              | Validation rules for the editable cell.                                                                                                                      |
+| `class`             | `string`                                                       | --              | CSS class applied to header and body cells.                                                                                                                  |
+| `headerClass`       | `string`                                                       | --              | CSS class applied only to the header cell.                                                                                                                   |
+| `bodyClass`         | `string`                                                       | --              | CSS class applied only to body cells.                                                                                                                        |
+| `lineClamp`         | `number`                                                       | `2`             | Max lines to display before truncating. `0` = no clamp.                                                                                                      |
+| `selectionMode`     | `"single" \| "multiple"`                                       | --              | Renders a selection checkbox/radio column.                                                                                                                   |
+| `rowEditor`         | `boolean`                                                      | `false`         | Renders save/cancel buttons for row edit mode.                                                                                                               |
+| `rowReorder`        | `boolean`                                                      | `false`         | Renders a drag handle for row reordering.                                                                                                                    |
+| `expander`          | `boolean`                                                      | `false`         | Renders an expand/collapse toggle.                                                                                                                           |
+| `mobileRole`        | `"title" \| "image" \| "field" \| "status"`                    | --              | Role in mobile card layout.                                                                                                                                  |
+| `mobilePosition`    | `"top-left" \| "top-right" \| "bottom-left" \| "bottom-right"` | --              | Explicit grid position for the mobile card layout.                                                                                                           |
+| `mobileVisible`     | `boolean`                                                      | `true`          | Whether column is visible on mobile.                                                                                                                         |
 
 ### Slots
 
@@ -1434,13 +1447,13 @@ function onRowRemove(event: { data: Product; index: number; cancel: () => void }
 
 ### Sorting
 
-| Prop            | Type                     | Default    | Description                                            |
-| --------------- | ------------------------ | ---------- | ------------------------------------------------------ |
-| `sortField`     | `string`                 | --         | Currently sorted field. Use with `v-model:sortField`.  |
-| `sortOrder`     | `1 \| -1 \| 0`           | `0`        | Sort direction. Use with `v-model:sortOrder`.          |
-| `sortMode`      | `"single" \| "multiple"` | `"single"` | Single or multi-column sort.                           |
-| `multiSortMeta` | `SortMeta[]`             | `[]`       | Multi-sort metadata. Use with `v-model:multiSortMeta`. |
-| `removableSort` | `boolean`                | `false`    | Allow 3-state sort cycle (asc -> desc -> none).        |
+| Prop            | Type                     | Default    | Description                                                                |
+| --------------- | ------------------------ | ---------- | -------------------------------------------------------------------------- |
+| `sortField`     | `string`                 | --         | Currently sorted field. Use with `v-model:sortField`.                      |
+| `sortOrder`     | `1 \| -1 \| 0`           | `0`        | Sort direction. Use with `v-model:sortOrder`.                              |
+| `sortMode`      | `"single" \| "multiple"` | `"single"` | Single or multi-column sort.                                               |
+| `multiSortMeta` | `SortMeta[]`             | `[]`       | Multi-sort metadata. Use with `v-model:multiSortMeta`.                     |
+| `removableSort` | `boolean`                | `true`     | 3-state sort cycle (asc -> desc -> none). Set `false` for a 2-state cycle. |
 
 ### Editing
 
@@ -2070,6 +2083,21 @@ const isSelectable = (item) => item.stock > 0;
 <VcDataTable :items="orders" state-key="orders-list">...</VcDataTable>
 ```
 
+### 9. Not resetting the page when the search changes
+
+```ts
+// WRONG: search persists, but the page is not reset.
+// On a later page, the URL keeps `_page=3`; reloading a narrow search
+// requests page 3 of the filtered set → empty "nothing found" on reload.
+const { searchValue } = useTableSearch({ stateKey: "products_list" });
+watch([sortExpression, searchValue, () => pagination.skip], load);
+
+// CORRECT: reset to page 1 before reloading on a new keyword.
+const { searchValue } = useTableSearch({ stateKey: "products_list" });
+watch(searchValue, () => pagination.setPage(1));
+watch([sortExpression, searchValue, () => pagination.skip], load);
+```
+
 ---
 
 ## Related Components

package/runtime/knowledge/docs/ui/components/organisms/vc-dynamic-property/vc-dynamic-property.docs.md

@@ -46,20 +46,25 @@ The prop names match the `DynamicObjectProperty` shape returned by the platform
 
 ## Key Props
 
-| Prop                 | Type       | Default | Description                                                                   |
-| -------------------- | ---------- | ------- | ----------------------------------------------------------------------------- |
-| `property`           | `T`        | -       | Property object with `id` and metadata                                        |
-| `modelValue`         | `any`      | -       | Current property value (v-model)                                              |
-| `valueType`          | `string`   | -       | Type: ShortText, LongText, Number, Integer, DateTime, Boolean, Measure, Color |
-| `name`               | `string`   | -       | Property name for display and field identification                            |
-| `required`           | `boolean`  | -       | Whether the field is required                                                 |
-| `disabled`           | `boolean`  | `false` | Disables the input                                                            |
-| `dictionary`         | `boolean`  | `false` | Uses VcSelect/VcMultivalue with options                                       |
-| `multivalue`         | `boolean`  | `false` | Supports multiple values                                                      |
-| `multilanguage`      | `boolean`  | `false` | Supports localized values                                                     |
-| `optionsGetter`      | `Function` | -       | Async loader for dictionary options                                           |
-| `measurementsGetter` | `Function` | -       | Async loader for measurement units                                            |
-| `rules`              | `object`   | -       | Validation rules: `{ min, max, regex }`                                       |
+| Prop                 | Type                         | Default    | Description                                                                                                                                              |
+| -------------------- | ---------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `property`           | `T`                          | _required_ | Property object with `id` and metadata                                                                                                                   |
+| `modelValue`         | `any`                        | _required_ | Current property value (v-model)                                                                                                                         |
+| `valueType`          | `string`                     | _required_ | Type: ShortText, LongText, Number, Integer, DateTime, Boolean, Measure, Color                                                                            |
+| `name`               | `string`                     | _required_ | Property name for display and field identification                                                                                                       |
+| `required`           | `boolean`                    | _required_ | Whether the field is required                                                                                                                            |
+| `disabled`           | `boolean`                    | `false`    | Disables the input                                                                                                                                       |
+| `dictionary`         | `boolean`                    | `false`    | Uses VcSelect/VcMultivalue with options                                                                                                                  |
+| `multivalue`         | `boolean`                    | `false`    | Supports multiple values                                                                                                                                 |
+| `multilanguage`      | `boolean`                    | `false`    | Supports localized values                                                                                                                                |
+| `currentLanguage`    | `string`                     | -          | Active locale used for localized values                                                                                                                  |
+| `optionsGetter`      | `Function`                   | _required_ | Async loader for dictionary options, called as `(propertyId, keyword?, locale?)`                                                                         |
+| `measurementsGetter` | `Function`                   | -          | Async loader for measurement units                                                                                                                       |
+| `optionsValue`       | `string`                     | `"id"`     | Field on each option used as its value (VcSelect mapping)                                                                                                |
+| `optionsLabel`       | `string`                     | `"value"`  | Inert. The option label is fixed to `"value"` when `multilanguage` is true and `"alias"` otherwise; only `optionsValue` is honored for VcSelect mapping. |
+| `displayNames`       | `{ name?; languageCode? }[]` | -          | Localized display names used to resolve the field label per locale                                                                                       |
+| `placeholder`        | `string`                     | -          | Placeholder text for the input                                                                                                                           |
+| `rules`              | `object`                     | -          | Validation rules: `{ min, max, regex }`                                                                                                                  |
 
 ::storybook id="data-display-vcdynamicproperty--property-form" height="500"
 
@@ -99,8 +104,8 @@ async function loadProperties() {
   properties.value = result;
 }
 
-async function loadDictionaryOptions(propertyId: string, keyword?: string) {
-  return await api.searchDictionaryItems(propertyId, keyword);
+async function loadDictionaryOptions(propertyId: string, keyword?: string, locale?: string) {
+  return await api.searchDictionaryItems(propertyId, keyword, locale);
 }
 
 function handlePropertyUpdate(property: any, newValue: any) {
@@ -121,25 +126,27 @@ function handlePropertyUpdate(property: any, newValue: any) {
       :dictionary="prop.isDictionary"
       :multivalue="prop.isMultivalue"
       :multilanguage="prop.isMultilanguage"
-      :options-getter="(kw) => loadDictionaryOptions(prop.id, kw)"
-      @update:model-value="(val) => handlePropertyUpdate(prop, val)"
+      :options-getter="loadDictionaryOptions"
+      @update:model-value="(payload) => handlePropertyUpdate(prop, payload.value)"
     />
   </div>
 </template>
 ```
 
+`update:model-value` emits an object, not a raw value: `{ value, dictionary?, locale?, unitOfMeasureId?, colorCode? }`. Read `payload.value` for the primary value; the other keys carry dictionary items, the active locale, the selected measure unit, and a color code where applicable. `optionsGetter` is invoked as `(propertyId, keyword?, locale?)` — bind it directly rather than wrapping the property id into the first argument.
+
 ::storybook id="data-display-vcdynamicproperty--required-with-validation" height="300"
 
 ## Recipe: Dynamic Property with Validation
 
 ```vue
-<VcDynamicProperty :property="skuProperty" :model-value="skuProperty.values?.[0]?.value" value-type="ShortText" name="SKU" :required="true" :rules="{ regex: '^[A-Z0-9-]+$', min: 3, max: 50 }" @update:model-value="(val) => updateProperty(skuProperty, val)" />
+<VcDynamicProperty :property="skuProperty" :model-value="skuProperty.values?.[0]?.value" value-type="ShortText" name="SKU" :required="true" :rules="{ regex: '^[A-Z0-9-]+$', min: 3, max: 50 }" @update:model-value="(payload) => updateProperty(skuProperty, payload.value)" />
 ```
 
 ## Recipe: Measurement Property with Units
 
 ```vue
-<VcDynamicProperty :property="weightProperty" :model-value="weightProperty.values?.[0]?.value" value-type="Measure" name="Weight" :measurements-getter="loadMeasurementUnits" @update:model-value="(val) => updateProperty(weightProperty, val)" />
+<VcDynamicProperty :property="weightProperty" :model-value="weightProperty.values?.[0]?.value" value-type="Measure" name="Weight" :measurements-getter="loadMeasurementUnits" @update:model-value="(payload) => updateProperty(weightProperty, payload.value)" />
 ```
 
 ## Common Mistakes

package/runtime/knowledge/docs/ui/components/organisms/vc-gallery/vc-gallery.docs.md

@@ -29,7 +29,7 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 | `multiple`      | `boolean`                                                 | `false`                                       | Allow selecting multiple files in upload dialog.                                                                                                                                            |
 | `loading`       | `boolean`                                                 | `false`                                       | Shows a loading overlay with spinner on the gallery.                                                                                                                                        |
 | `itemActions`   | `{ preview?: boolean; edit?: boolean; remove?: boolean }` | `{ preview: true, edit: true, remove: true }` | Per-tile action visibility.                                                                                                                                                                 |
-| `rules`         | `IValidationRules`                                        | `undefined`                                   | Validation rules for uploaded files.                                                                                                                                                        |
+| `rules`         | `keyof IValidationRules \| IValidationRules`              | `undefined`                                   | Validation rules for uploaded files.                                                                                                                                                        |
 | `name`          | `string`                                                  | `"Gallery"`                                   | Field name for validation messages.                                                                                                                                                         |
 | `accept`        | `string`                                                  | `"image/*"`                                   | Accepted file MIME types / extensions. Gallery is image-only by default — non-image files dropped from the OS are filtered out. Override (e.g. `"image/png,image/jpeg"`) to narrow further. |
 | `size`          | `"sm" \| "md" \| "lg"`                                    | `"md"`                                        | Tile size preset. Sizes are smaller on mobile.                                                                                                                                              |
@@ -190,6 +190,6 @@ function handleRemove(image: ICommonAsset) {
 ## Related Components
 
 - **VcImageUpload** -- single-image upload component
-- **VcImageTile** -- the internal tile component used for each image (topbar with name + drag handle, bottom tray with actions)
+- **VcGalleryItem** -- the internal tile component (`_internal/vc-gallery-item`) rendered for each image (topbar with name + drag handle, bottom tray with actions)
 - **VcFileUpload** -- the file upload drop zone used in empty gallery state
 - **VcLabel** -- used internally when `label` prop is set

package/runtime/knowledge/docs/ui/components/organisms/vc-image-upload/vc-image-upload.docs.md

@@ -19,18 +19,18 @@ A single-image upload organism that displays either a drag-and-drop upload zone
 
 ## Props
 
-| Prop          | Type                             | Default                            | Description                                    |
-| ------------- | -------------------------------- | ---------------------------------- | ---------------------------------------------- |
-| `image`       | `ICommonAsset`                   | `undefined`                        | The currently displayed image asset.           |
-| `disabled`    | `boolean`                        | `false`                            | Disables upload and remove actions.            |
-| `loading`     | `boolean`                        | `false`                            | Shows a loading spinner on the upload zone.    |
-| `accept`      | `string`                         | `.jpg,.png,.jpeg,.webp,.heic,.svg` | Accepted file extensions.                      |
-| `rules`       | `IValidationRules`               | `undefined`                        | Validation rules (e.g. `{ fileWeight: 300 }`). |
-| `name`        | `string`                         | `"Image"`                          | Field name for validation messages.            |
-| `icon`        | `string`                         | `"lucide-cloud-upload"`            | Upload zone placeholder icon.                  |
-| `placeholder` | `{ text: string; link: string }` | `undefined`                        | Custom text for the upload zone.               |
-| `previewable` | `boolean`                        | `true`                             | Enables lightbox preview on click.             |
-| `removable`   | `boolean`                        | `true`                             | Shows the remove action on the image tile.     |
+| Prop          | Type                                         | Default                            | Description                                                         |
+| ------------- | -------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------- |
+| `image`       | `ICommonAsset`                               | `undefined`                        | The currently displayed image asset.                                |
+| `disabled`    | `boolean`                                    | `false`                            | Disables upload and remove actions.                                 |
+| `loading`     | `boolean`                                    | `false`                            | Shows a loading spinner on the upload zone.                         |
+| `accept`      | `string`                                     | `.jpg,.png,.jpeg,.webp,.heic,.svg` | Accepted file extensions.                                           |
+| `rules`       | `keyof IValidationRules \| IValidationRules` | `undefined`                        | Validation rules (rule name or object, e.g. `{ fileWeight: 300 }`). |
+| `name`        | `string`                                     | `"Image"`                          | Field name for validation messages.                                 |
+| `icon`        | `string`                                     | `"lucide-cloud-upload"`            | Upload zone placeholder icon.                                       |
+| `placeholder` | `{ text: string; link: string }`             | `undefined`                        | Custom text for the upload zone.                                    |
+| `previewable` | `boolean`                                    | `true`                             | Enables lightbox preview on click.                                  |
+| `removable`   | `boolean`                                    | `true`                             | Shows the remove action on the image tile.                          |
 
 ## Events
 

package/runtime/knowledge/docs/ui/components/organisms/vc-popup/vc-popup.docs.md

@@ -74,12 +74,14 @@ The `variant` prop adds a semantic icon and color to the popup. Available values
 
 When `variant` is anything other than `"default"`, a large icon is rendered to the left of the content area:
 
-| Variant   | Icon                    | Color token     |
-| --------- | ----------------------- | --------------- |
-| `warning` | `lucide-triangle-alert` | `--warning-500` |
-| `error`   | `lucide-circle-alert`   | `--danger-500`  |
-| `success` | `lucide-circle-check`   | `--success-500` |
-| `info`    | `lucide-info`           | `--info-500`    |
+| Variant   | Icon                    | Color token (default value)                    |
+| --------- | ----------------------- | ---------------------------------------------- |
+| `warning` | `lucide-triangle-alert` | `--popup-warning-icon-color` (`--warning-500`) |
+| `error`   | `lucide-circle-alert`   | `--popup-error-icon-color` (`--danger-500`)    |
+| `success` | `lucide-circle-check`   | `--popup-success-icon-color` (`--success-500`) |
+| `info`    | `lucide-info`           | `--popup-info-icon-color` (`--info-500`)       |
+
+The icon color is overridable per variant via `--popup-<variant>-icon-color`.
 
 ### Title
 
@@ -140,10 +142,9 @@ The `close` event carries a `PopupCloseReason` string so you can react different
 </VcPopup>
 
 <script setup lang="ts">
-import type { PopupCloseReason } from "@vc-shell/framework";
-
-function onClose(reason?: PopupCloseReason) {
-  // reason is "overlay" | "escape" | "action"
+// The reason is the union `"overlay" | "escape" | "action"`.
+// (`PopupCloseReason` is internal to vc-popup.vue and is not re-exported from the framework entry.)
+function onClose(reason?: "overlay" | "escape" | "action") {
   if (reason === "action") {
     // User clicked a button
   }
@@ -238,10 +239,10 @@ The `modalWidth` prop accepts a Tailwind CSS max-width class. The default is `"t
 
 Two props control fullscreen behavior:
 
-| Prop                 | Effect                                                                  |
-| -------------------- | ----------------------------------------------------------------------- |
-| `isFullscreen`       | Full viewport on **all** screen sizes                                   |
-| `isMobileFullscreen` | Full viewport on **mobile only** (detected via `IsMobileKey` injection) |
+| Prop                 | Effect                                                                       |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `isFullscreen`       | Full viewport on **all** screen sizes                                        |
+| `isMobileFullscreen` | Full viewport on **mobile only** (detected via `useResponsive()` `isMobile`) |
 
 ```vue
 <VcPopup v-model="open" title="Image Editor" is-fullscreen>
@@ -546,16 +547,24 @@ Or display a richer error popup in-template:
 
 ## CSS Custom Properties
 
-| Variable                     | Default                | Description                          |
-| ---------------------------- | ---------------------- | ------------------------------------ |
-| `--popup-border-radius`      | `6px`                  | Border radius of the dialog panel    |
-| `--popup-shadow`             | `var(--shadow-md)`     | Box shadow around the panel          |
-| `--popup-overlay-blur`       | `var(--overlay-blur)`  | Backdrop blur amount                 |
-| `--popup-bg`                 | `var(--additional-50)` | Background color of the dialog panel |
-| `--popup-header-color`       | `var(--primary-700)`   | Title text color                     |
-| `--popup-content-text-color` | `var(--primary-700)`   | Content text color                   |
-| `--popup-footer-separator`   | `var(--neutrals-200)`  | Footer top border color              |
-| `--popup-overlay`            | `var(--overlay-bg)`    | Overlay background color             |
+> **Note:** New themes should override `--vc-popup-border-radius`, `--vc-popup-shadow`, and `--vc-popup-overlay-blur`. The `--popup-*` variables below are deprecated aliases kept for backward compatibility (the `--vc-popup-*` vars fall back to them).
+
+| Variable                     | Default                                                  | Description                          |
+| ---------------------------- | -------------------------------------------------------- | ------------------------------------ |
+| `--popup-border-radius`      | `6px`                                                    | Border radius of the dialog panel    |
+| `--popup-shadow`             | `var(--shadow-md)`                                       | Box shadow around the panel          |
+| `--popup-overlay-blur`       | `var(--overlay-blur)`                                    | Backdrop blur amount                 |
+| `--popup-bg`                 | `var(--additional-50)`                                   | Background color of the dialog panel |
+| `--popup-header-color`       | `var(--primary-700)`                                     | Title text color                     |
+| `--popup-content-text-color` | `var(--primary-700)`                                     | Content text color                   |
+| `--popup-footer-separator`   | `var(--neutrals-200)`                                    | Footer top border color              |
+| `--popup-overlay`            | `var(--overlay-bg)`                                      | Overlay background color             |
+| `--popup-close-btn-bg`       | `var(--neutrals-100)`                                    | Close button (X) background          |
+| `--popup-close-btn-bg-hover` | `color-mix(in srgb, var(--popup-close-btn-bg), #000 5%)` | Close button background on hover     |
+| `--popup-warning-icon-color` | `var(--warning-500)`                                     | Warning variant icon color           |
+| `--popup-error-icon-color`   | `var(--danger-500)`                                      | Error variant icon color             |
+| `--popup-success-icon-color` | `var(--success-500)`                                     | Success variant icon color           |
+| `--popup-info-icon-color`    | `var(--info-500)`                                        | Info variant icon color              |
 
 ## Accessibility