@vc-shell/vc-app-skill 2.1.0 → 2.2.0-pr260.a8bd3a7

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

@@ -53,7 +53,6 @@ Use VcBlade for every screen in a vc-shell application -- it is the standard con
   <VcBlade
     title="My First Blade"
     icon="lucide-box"
-    @close="$emit('close:blade')"
   >
     <div class="tw-p-4">Hello from a blade!</div>
   </VcBlade>
@@ -64,6 +63,9 @@ defineBlade({ name: "MyFirstBlade", url: "/my-first-blade" });
 </script>
 ```
 
+!!! tip "No close/expand wiring needed"
+Inside the navigation stack VcBlade closes itself and reads its expanded/closable state from the stack automatically. You don't declare `expanded`/`closable` props or forward `@close`/`@expand`/`@collapse` events — that wiring is a legacy fallback kept only for standalone (Storybook) use.
+
 !!! tip "Every blade needs a name"
 Every blade must define a `name` in `defineBlade`. This is how other blades reference it: `openBlade({ name: "MyFirstBlade" })`. The `url` is optional and controls the URL segment.
 
@@ -101,14 +103,9 @@ A blade has four visual zones, rendered top-to-bottom:
     :title="title"
     icon="lucide-tag"
     width="50%"
-    :expanded="expanded"
-    :closable="closable"
     :toolbar-items="toolbar"
     :modified="hasChanges"
     :loading="isLoading"
-    @close="$emit('close:blade')"
-    @expand="$emit('expand:blade')"
-    @collapse="$emit('collapse:blade')"
   >
     <!-- Your content here -->
   </VcBlade>
@@ -125,29 +122,13 @@ defineBlade({
   routable: false, // Optional: exclude from direct URL access
 });
 
-// Standard props injected by the navigation system
-export interface Props {
-  expanded: boolean;
-  closable: boolean;
-  param?: string; // Entity ID
-  options?: { sellerProduct?: object };
-}
-
-const props = withDefaults(defineProps<Props>(), {
-  expanded: true,
-  closable: true,
-});
-
-export interface Emits {
-  (event: "close:blade"): void;
-  (event: "expand:blade"): void;
-  (event: "collapse:blade"): void;
-}
-const emit = defineEmits<Emits>();
-
-const { openBlade, closeSelf, callParent, onBeforeClose } = useBlade();
+// Navigation state and data come from useBlade() — not props.
+// `param` (entity id) and `options` (rich context) are reactive refs.
+const { openBlade, closeSelf, callParent, onBeforeClose, param, options } = useBlade<{
+  sellerProduct?: object;
+}>();
 
-const title = computed(() => (props.param ? "Edit Offer" : "New Offer"));
+const title = computed(() => (param.value ? "Edit Offer" : "New Offer"));
 const isLoading = ref(false);
 const hasChanges = ref(false);
 
@@ -166,15 +147,18 @@ defineExpose({ title });
 </script>
 ```
 
+!!! warning "Legacy pattern: `expanded` / `closable` props and `close:blade` emits"
+Older blades declared `defineProps<{ expanded; closable; param }>()`, wired `withDefaults`, and re-emitted `close:blade` / `expand:blade` / `collapse:blade`. This is no longer needed. The navigation stack owns expanded/closable state (a workspace root is not closable, the rightmost blade is expanded), and VcBlade closes itself. Read `param`, `options`, `query`, `expanded`, and `closable` from `useBlade()` instead — see [useBlade docs](../../../../core/composables/useBlade/useBlade.docs.md).
+
 ### defineOptions Reference
 
-| Property      | Type      | Description                                                             |
-| ------------- | --------- | ----------------------------------------------------------------------- |
-| `name`        | `string`  | **Required.** Unique blade identifier for `openBlade({ name: "..." })`. |
-| `url`         | `string`  | URL path segment (e.g., `"/offers"` produces `/#/.../offers`).          |
-| `isWorkspace` | `boolean` | Marks blade as a workspace (root-level, not closable).                  |
-| `routable`    | `boolean` | When `false`, blade cannot be opened via direct URL navigation.         |
-| `menuItem`    | `object`  | Registers a sidebar menu entry: `{ id, title, icon, priority }`.        |
+| Property      | Type      | Description                                                                                                        |
+| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------ |
+| `name`        | `string`  | **Required.** Unique blade identifier for `openBlade({ name: "..." })`.                                            |
+| `url`         | `string`  | URL path segment (e.g., `"/offers"` produces `/#/.../offers`).                                                     |
+| `isWorkspace` | `boolean` | Marks blade as a workspace (root-level, not closable).                                                             |
+| `routable`    | `boolean` | When `false`, blade cannot be opened via direct URL navigation.                                                    |
+| `menuItem`    | `object`  | Registers a sidebar menu entry: `{ title, icon, priority }` (plus optional `groupConfig`, `permissions`, `badge`). |
 
 ### defineExpose
 
@@ -310,10 +294,13 @@ const entityId = computed(() => ctx.value.item?.id);
 
 ### Expanded / Collapsed
 
-`expanded` indicates whether this blade is the active (rightmost) one. The navigation system manages it -- just pass through:
+`expanded` indicates whether this blade is the active (rightmost) one. The navigation system manages it entirely -- **don't** declare an `expanded` prop or forward `@expand`/`@collapse`. If you need the current value, read it reactively from `useBlade()`:
 
-```vue
-<VcBlade :expanded="expanded" @expand="$emit('expand:blade')" @collapse="$emit('collapse:blade')">
+```ts
+const { expanded } = useBlade();
+
+// e.g. show a compact layout when this blade is collapsed behind others
+const layout = computed(() => (expanded.value ? "full" : "compact"));
 ```
 
 ### Closing
@@ -372,10 +359,11 @@ interface IBladeToolbar {
   id?: string;
   title?: string | Ref<string> | ComputedRef<string>;
   icon?: string | (() => string);
-  clickHandler?(): void;
-  disabled?: boolean | ComputedRef<boolean>;
-  isVisible?: boolean | Ref<boolean> | ComputedRef<boolean> | ((blade?: BladeDescriptor) => boolean);
+  clickHandler?(app?: Record<string, any> | null): void;
+  disabled?: boolean | ComputedRef<boolean | undefined>;
+  isVisible?: boolean | Ref<boolean | undefined> | ComputedRef<boolean | undefined> | ((blade?: BladeDescriptor) => boolean | undefined);
   separator?: "left" | "right" | "both";
+  permissions?: string | string[];
 }
 ```
 
@@ -555,7 +543,7 @@ const toolbar = ref([
 ### Blade with Data Table
 
 ```vue
-<VcBlade :title="$t('ORDERS.LIST.TITLE')" icon="lucide-file-text" width="50%" :expanded="expanded" :closable="closable" :toolbar-items="toolbar">
+<VcBlade :title="$t('ORDERS.LIST.TITLE')" icon="lucide-file-text" width="50%" :toolbar-items="toolbar">
   <VcDataTable
     v-model:sort-field="sortField" v-model:sort-order="sortOrder"
     v-model:search-value="searchValue" v-model:active-item-id="selectedItemId"
@@ -582,16 +570,6 @@ defineOptions({});
 defineBlade({ name: "ProductDetails", url: "/product" });
 ```
 
-### Forgetting to expose the title
-
-```ts
-// WRONG -- Breadcrumbs show nothing
-const title = computed(() => product.value?.name);
-
-// CORRECT
-defineExpose({ title });
-```
-
 ### Wrong onBeforeClose return value
 
 ```ts
@@ -614,37 +592,29 @@ const { openBlade } = useBlade();
 openBlade({ name: "ProductsList" });
 ```
 
-### Not passing expanded/closable through
-
-```vue
-<!-- WRONG -- hardcoded, ignores navigation system -->
-<VcBlade :expanded="true" :closable="true">
-
-<!-- CORRECT -- pass props from navigation -->
-<VcBlade :expanded="expanded" :closable="closable">
-```
-
 ## Props
 
-| Prop           | Type               | Default     | Description                                                                                                                                                                               |
-| -------------- | ------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `title`        | `string`           | `undefined` | Title text in the blade header.                                                                                                                                                           |
-| `subtitle`     | `string`           | `undefined` | Secondary text below the title.                                                                                                                                                           |
-| `icon`         | `string`           | `undefined` | Icon name (e.g., `"lucide-box"`) displayed before the title.                                                                                                                              |
-| `width`        | `number \| string` | `"30%"`     | Blade width. Numbers are pixels; strings are CSS values.                                                                                                                                  |
-| `expanded`     | `boolean`          | `undefined` | Whether the blade fills all available width. Inside a blade-navigation context this prop is overridden by the active blade's expanded state; in standalone use the prop is read directly. |
-| `closable`     | `boolean`          | `true`      | Whether the close button is shown.                                                                                                                                                        |
-| `toolbarItems` | `IBladeToolbar[]`  | `[]`        | Action buttons in the toolbar zone.                                                                                                                                                       |
-| `modified`     | `boolean`          | `undefined` | Shows unsaved changes indicator and banner.                                                                                                                                               |
-| `loading`      | `boolean`          | `undefined` | Shows skeleton placeholders for all blade zones.                                                                                                                                          |
+| Prop           | Type               | Default     | Description                                                                                                                                                                                                                                                               |
+| -------------- | ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`        | `string`           | `undefined` | Title text in the blade header.                                                                                                                                                                                                                                           |
+| `subtitle`     | `string`           | `undefined` | Secondary text below the title.                                                                                                                                                                                                                                           |
+| `icon`         | `string`           | `undefined` | Icon name (e.g., `"lucide-box"`) displayed before the title.                                                                                                                                                                                                              |
+| `width`        | `number \| string` | `"30%"`     | Blade width. Numbers are pixels; strings are CSS values.                                                                                                                                                                                                                  |
+| ~~`expanded`~~ | `boolean`          | `undefined` | **Deprecated.** Managed by the navigation stack — ignored inside blade navigation, where the active (rightmost) blade is expanded automatically. Read the live value from `useBlade().expanded`. Retained only as a standalone/Storybook fallback.                        |
+| ~~`closable`~~ | `boolean`          | `true`      | **Deprecated.** Managed by the navigation stack — ignored inside blade navigation, where closability is derived from stack position (a workspace root is not closable). Read the live value from `useBlade().closable`. Retained only as a standalone/Storybook fallback. |
+| `toolbarItems` | `IBladeToolbar[]`  | `[]`        | Action buttons in the toolbar zone.                                                                                                                                                                                                                                       |
+| `modified`     | `boolean`          | `undefined` | Shows unsaved changes indicator and banner.                                                                                                                                                                                                                               |
+| `loading`      | `boolean`          | `undefined` | Shows skeleton placeholders for all blade zones.                                                                                                                                                                                                                          |
 
 ## Events
 
-| Event      | Payload | Description                                     |
-| ---------- | ------- | ----------------------------------------------- |
-| `close`    | --      | Close button clicked. Re-emit as `close:blade`. |
-| `expand`   | --      | Blade expanded. Re-emit as `expand:blade`.      |
-| `collapse` | --      | Blade collapsed. Re-emit as `collapse:blade`.   |
+> **Note:** These events fire **only in standalone/Storybook use**. Inside the navigation stack VcBlade closes itself (via `closeSelf()`) and handles expand/collapse internally, so there is nothing to forward. Use `onBeforeClose()` from `useBlade()` to run logic (like an unsaved-changes guard) before the blade closes. A leftover `@close` listener inside blade navigation triggers a dev-mode deprecation warning.
+
+| Event      | Payload | Description                                                        |
+| ---------- | ------- | ------------------------------------------------------------------ |
+| `close`    | --      | Standalone only. Close button clicked.                             |
+| `expand`   | --      | Standalone only. Blade expanded (no `maximized` context present).  |
+| `collapse` | --      | Standalone only. Blade collapsed (no `maximized` context present). |
 
 ## Slots
 

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

@@ -73,20 +73,18 @@ The central engine. Distributes `availableWidth` among visible columns according
 
 ```ts
 interface EngineInput {
-  visibleIds: string[]; // Ordered list of visible column IDs
-  specs: Record<string, ColumnSpec>; // Per-column: weight, minWidth, maxWidth
   availableWidth: number; // Container width in px
-  fitMode: "gap" | "fit"; // "gap" leaves filler space, "fit" fills width
+  columns: { id: string; spec: ColumnSpec }[]; // Ordered visible columns with per-column weight, minPx, maxPx
+  mode: "fit" | "gap"; // "gap" leaves filler space, "fit" fills width
 }
 
 interface EngineOutput {
   widths: Record<string, number>; // Computed px width per column ID
-  totalWidth: number; // Sum of all computed widths
-  overflow: boolean; // true when sum(minWidth) > availableWidth
+  fillerWidth: number; // Leftover space returned to the filler pseudo-element
 }
 ```
 
-In crisis (`overflow: true`), each column receives its `minWidth` regardless of weight, and a console warning is emitted.
+In crisis (when `sum(minPx) > availableWidth`), the engine squeezes columns proportionally below their minimums (`crisisSqueeze`) and emits a `console.warn`.
 
 #### `parseColumnWidth(value: string | number | undefined, availableWidth: number): ParsedWidth`
 
@@ -94,14 +92,14 @@ Parses a `VcColumn` `width` prop into a concrete pixel value.
 
 ```ts
 type ParsedWidth =
-  | { type: "px"; value: number } // "200", 200, "200px"
-  | { type: "pct"; value: number } // "20%" → 0.2 * availableWidth
-  | { type: "auto"; value: undefined }; // undefined, "auto"
+  | { type: "px"; desiredPx: number } // "200", 200, "200px"
+  | { type: "percent"; desiredPx: number } // "20%" → 0.2 * availableWidth
+  | { type: "auto"; desiredPx: null }; // undefined, "auto"
 ```
 
-#### `buildInitialWeights(parsed: ParsedWidth[], availableWidth: number): Record<string, number>`
+#### `buildInitialWeights(parsed: { id: string; parsed: ParsedWidth }[], availableWidth: number): Record<string, number>`
 
-Converts an array of `ParsedWidth` values (one per column) into initial weights. Auto columns receive an equal share of the space not claimed by px/% columns.
+Converts an array of `{ id, parsed }` entries (one per column) into initial weights. Auto columns receive an equal share of the space not claimed by px/% columns.
 
 ```ts
 // Example: three columns — 200px, 20%, auto — with 800px available

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