@vc-shell/vc-app-skill 2.0.0-alpha.30 → 2.0.0-alpha.32

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# [2.0.0-alpha.32](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.31...v2.0.0-alpha.32) (2026-04-02)
+
+**Note:** Version bump only for package @vc-shell/vc-app-skill
+
+# [2.0.0-alpha.31](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.30...v2.0.0-alpha.31) (2026-04-01)
+
+**Note:** Version bump only for package @vc-shell/vc-app-skill
+
 # [2.0.0-alpha.30](https://github.com/VirtoCommerce/vc-shell/compare/v2.0.0-alpha.29...v2.0.0-alpha.30) (2026-03-30)
 
 

package/package.json

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

package/runtime/VERSION

@@ -1 +1 @@
-2.0.0-alpha.30
+2.0.0-alpha.32

package/runtime/knowledge/docs/_BUILD_HASH.md

@@ -1 +1 @@
-Synced from framework at commit 37522732b on 2026-03-30T14:31:59.196Z
+Synced from framework at commit fc29b1e1b on 2026-04-02T05:22:47.427Z

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

@@ -0,0 +1,113 @@
+# useBladeForm
+
+Unified form state management for blades. Replaces manual combination of `useForm` + `useModificationTracker` + `useBeforeUnload` + `onBeforeClose` with a single composable.
+
+## Import
+
+```ts
+import { useBladeForm } from "@vc-shell/framework";
+```
+
+## Basic Usage
+
+```ts
+const { item, loadItem, saveItem } = useItemData();
+
+const form = useBladeForm({ data: item });
+
+onMounted(async () => {
+  await loadItem({ id: param.value });
+  form.setBaseline(); // snapshot current data as pristine
+});
+
+// Toolbar
+const toolbar = ref<IBladeToolbar[]>([
+  {
+    id: "save",
+    title: "Save",
+    icon: "lucide-save",
+    disabled: computed(() => !form.canSave.value),
+    async clickHandler() {
+      await saveItem(item.value);
+      form.setBaseline(); // snapshot after save
+      callParent("reload");
+    },
+  },
+]);
+```
+
+## API
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `data` | `Ref<T>` | required | Reactive data object for the form |
+| `canSaveOverride` | `ComputedRef<boolean>` | — | Additional condition for canSave |
+| `autoBeforeClose` | `boolean \| ComputedRef<boolean>` | `true` | Close guard behavior |
+| `autoBeforeUnload` | `boolean` | `true` | Browser tab close guard |
+| `closeConfirmMessage` | `MaybeRefOrGetter<string>` | — | Custom unsaved changes message |
+| `onRevert` | `() => void \| Promise<void>` | — | Custom revert handler |
+
+### Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `setBaseline()` | `() => void` | Snapshot current data as pristine. Call after load and after save |
+| `revert()` | `() => void \| Promise<void>` | Revert data to pristine (or call onRevert) |
+| `canSave` | `ComputedRef<boolean>` | `isReady && valid && modified && canSaveOverride` |
+| `isModified` | `ComputedRef<boolean>` | Data differs from pristine (false until setBaseline) |
+| `isReady` | `ComputedRef<boolean>` | setBaseline() called at least once |
+| `formMeta` | vee-validate meta | Form validation state |
+| `setFieldError` | function | Set field error programmatically |
+| `errorBag` | Ref | All field errors |
+
+## Lifecycle
+
+```
+Mount → Load data → setBaseline() → User edits → Save → setBaseline()
+                                                 └→ Cancel → revert()
+```
+
+## VcBlade Integration
+
+`useBladeForm` auto-provides form state to `VcBlade` via inject. No need to pass `:modified` prop:
+
+```vue
+<!-- Before -->
+<VcBlade :modified="isModified" :toolbar-items="toolbar">
+
+<!-- After -->
+<VcBlade :toolbar-items="toolbar">
+```
+
+## Advanced: Readonly Blade
+
+```ts
+const disabled = computed(() => !!param.value && !item.value?.canBeModified);
+
+const form = useBladeForm({
+  data: item,
+  canSaveOverride: computed(() => !disabled.value),
+  autoBeforeClose: computed(() => !disabled.value), // no prompt when readonly
+});
+```
+
+## Advanced: Custom Revert
+
+```ts
+const form = useBladeForm({
+  data: item,
+  onRevert: () => loadItem({ id: param.value }), // reload from server
+});
+```
+
+## Constraints
+
+- **Must be called from component `setup()`** (or `<script setup>`). Do NOT call from shared data-composables.
+- Validation rules stay in template (`<Field rules="...">`).
+- `setBaseline()` must be called after data is loaded — before that, `canSave` and `isModified` are `false`.
+
+## Migration
+
+See `MIGRATION_GUIDE.md` for step-by-step instructions on migrating existing modules.

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

@@ -1,163 +1,162 @@
 # useDynamicProperties
 
-Generic composable for managing dynamic (runtime-defined) property values with support for multilanguage, multivalue, dictionary, color, and measurement property types. This is one of the most complex composables in the framework because it must handle the combinatorial explosion of property configurations: a property can be multilanguage AND multivalue AND dictionary-backed, each combination requiring different get/set logic. The composable handles loading dictionary items from the API, getting/setting property values by locale, unit-of-measure lookups, and color code management.
+Composable for managing dynamic (runtime-defined) property values with support for multilanguage, multivalue, dictionary, color, and measurement property types.
 
-The composable is generic over the property, value, dictionary item, and measurement types, allowing it to work with both the standard platform types and custom extensions.
+Internally uses a strategy pattern — each property type (regular, boolean, dictionary, measure, color) has a dedicated handler with `get`/`set` methods.
 
 ## When to Use
 
 - In product, category, or any entity detail blades that display platform dynamic properties
 - When properties are defined at runtime (not compile-time) and may be multilanguage or dictionary-based
 - When you need to render and edit property values that can be text, boolean, number, datetime, dictionary selection, color picker, or measurement with units
-- When NOT to use: for static, compile-time form fields, use standard Vue reactive state. For simple key-value pairs without multilanguage/dictionary support, plain refs are sufficient.
+- When NOT to use: for static, compile-time form fields, use standard Vue reactive state
 
 ## Quick Start
 
 ```typescript
-import { useDynamicProperties } from '@vc-shell/framework';
-import { PropertyValue, PropertyDictionaryItem } from '@core/api/platform';
-
-const { loading, loadDictionaries, getPropertyValue, setPropertyValue, loadMeasurements } =
-  useDynamicProperties(
-    (criteria) => api.searchPropertyDictionaryItems(criteria),
-    PropertyValue,
-    PropertyDictionaryItem,
-    (measureId, locale) => api.searchMeasurements(measureId, locale),
-  );
+import { useDynamicProperties } from "@vc-shell/framework";
+
+const { getPropertyValue, setPropertyValue, loadDictionaries, loadMeasurements, loading } =
+  useDynamicProperties({
+    searchDictionary: (criteria) => api.searchPropertyDictionaryItems(criteria),
+    searchMeasurements: (measureId, locale) => api.searchMeasurements(measureId, locale),
+  });
 ```
 
 ## API
 
-### Parameters
+### Options
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `searchDictionaryItemsFunction` | `(criteria) => Promise<TPropertyDictionaryItem[] \| undefined>` | Yes | API function to search dictionary items by property ID and keyword. Called when the user opens a dictionary dropdown. |
-| `PropertyValueConstructor` | `new (data?) => TPropertyValue` | Yes | Constructor class for creating property value instances. Used when creating new values during `setPropertyValue`. |
-| `PropertyDictionaryItemConstructor` | `new (data?) => TPropertyDictionaryItem` | Yes | Constructor class for creating dictionary item instances. Used when localizing dictionary items. |
-| `searchMeasurementFunction` | `(measureId, locale?) => Promise<TMeasurement[] \| undefined>` | No | API function for loading measurement/unit-of-measure dictionaries. Only needed if you have measure-type properties. |
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `searchDictionary` | `(criteria: IBasePropertyDictionaryItemSearchCriteria) => Promise<IBasePropertyDictionaryItem[] \| undefined>` | Yes | API function to search dictionary items by property ID and keyword |
+| `searchMeasurements` | `(measureId: string, locale?: string) => Promise<IBaseMeasurementDictionaryItem[] \| undefined>` | No | API function for loading measurement units. Only needed for measure-type properties |
 
 ### Returns
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `loading` | `ComputedRef<boolean>` | Whether a dictionary or measurement lookup is in progress. |
-| `loadDictionaries` | `(propertyId, keyword?, locale?) => Promise<TPropertyDictionaryItem[] \| undefined>` | Loads dictionary items for a property. If `locale` is provided, resolves localized values from `localizedValues`. |
-| `getPropertyValue` | `(property, locale) => string \| TPropertyValue[] \| boolean` | Reads the display value for a property in the given locale. Returns string for simple values, array for multivalue, boolean for boolean type. |
-| `setPropertyValue` | `(params: SetPropertyValueParams) => void` | Writes a value to a property. Dispatches to specialized handlers based on property type (measure, color, dictionary, regular). |
-| `loadMeasurements` | `(measureId, keyword?, locale?) => Promise<TMeasurement[] \| undefined>` | Loads measurement units for a measure-type property. No-op if `searchMeasurementFunction` was not provided. |
+| `getPropertyValue` | `(property, locale) => PropertyDisplayValue` | Read display value for a property. Returns string, boolean, or array depending on type. Does NOT mutate the property. |
+| `setPropertyValue` | `(params: SetPropertyValueParams) => void` | Write value to a property. Handles type-specific transformation and empty cleanup. |
+| `loadDictionaries` | `(propertyId, keyword?, locale?) => Promise<...>` | Load dictionary items. If locale is provided, resolves localized values. |
+| `loadMeasurements` | `(measureId, keyword?, locale?) => Promise<...>` | Load measurement units. No-op if `searchMeasurements` was not provided. |
+| `loading` | `ComputedRef<boolean>` | Whether a dictionary lookup is in progress. |
 
 ### SetPropertyValueParams
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `property` | `TProperty` | The property object to update. Modified in place. |
-| `value` | `string \| TPropertyValue[] \| TPropertyDictionaryItem[]` | The new value. Type depends on property configuration. |
-| `dictionary` | `TPropertyDictionaryItem[]?` | Dictionary items for dictionary properties. Required when setting a dictionary value. |
+| `property` | `IBaseProperty` | The property object to update. Modified in place. |
+| `value` | `string \| IBasePropertyValue[] \| (IBasePropertyDictionaryItem & { value: string })[]` | The new value. Type depends on property configuration. |
+| `dictionary` | `IBasePropertyDictionaryItem[]?` | Dictionary items. Required when setting a dictionary value. |
 | `locale` | `string?` | Current locale for multilanguage properties. |
-| `initialProp` | `TProperty?` | Original property state. Used for empty-value detection -- if the original was empty and the new value is empty, a placeholder is preserved; otherwise, the value array is cleared. |
 | `unitOfMeasureId` | `string?` | Unit of measure ID for measure-type properties. |
 | `colorCode` | `string?` | Color hex code for color-type properties. |
 
+### PropertyDisplayValue
+
+```ts
+type PropertyDisplayValue = string | IBasePropertyValue[] | boolean;
+```
+
 ## How It Works
 
-### Value Getting
+### Strategy Resolution
 
-`getPropertyValue` dispatches based on property flags:
+The composable resolves a strategy handler based on property flags:
 
-- **Multilanguage**: Finds the value entry matching the locale. For multivalue, returns all entries for that locale as an array. For dictionary, returns the `valueId`. If no entry exists for the locale, creates a default entry using the first available alias.
-- **Single-language**: Returns the first value entry. For multivalue, returns all entries as an array. For dictionary, returns the `valueId`.
-- **Boolean**: Returns `false` if no value entry exists (instead of empty string).
+| Priority | Condition | Strategy | Handles |
+|----------|-----------|----------|---------|
+| 1 | `valueType === "Measure"` | measureStrategy | Numeric input with unit dropdown |
+| 2 | `valueType === "Color"` && !dictionary | colorStrategy | Color picker, multivalue colors |
+| 3 | `valueType === "Boolean"` | booleanStrategy | Checkbox/switch |
+| 4 | `dictionary === true` | dictionaryStrategy | Select dropdowns with localized options |
+| 5 | (default) | regularStrategy | ShortText, LongText, Number, Integer, DateTime |
 
-### Value Setting
+### Value Getting
 
-`setPropertyValue` checks property type in order:
-1. **Measure** (`valueType === "Measure"`): Creates a single value entry with `unitOfMeasureId`.
-2. **Color** (`valueType === "Color"`, no dictionary): Creates value entry/entries with `colorCode`.
-3. **Dictionary**: Resolves the selected dictionary item(s), expanding `localizedValues` into per-locale value entries for multilanguage dictionaries.
-4. **Regular**: Handles the remaining cases -- simple text, number, boolean, datetime.
+Each strategy's `get()` reads from `property.values` without mutation:
 
-### Dictionary Localization
+- **Multilanguage**: Finds value matching locale, falls back to value without languageCode
+- **Multivalue**: Returns full array (filtered by locale for multilanguage)
+- **Dictionary**: Returns `valueId` instead of `value`
+- **Boolean**: Returns `false` (not `""`) when no value exists
 
-When `loadDictionaries` is called with a locale, each dictionary item's `localizedValues` array is searched for the matching locale. The localized display value replaces the generic `alias` for UI rendering. This is why the function returns `Promise<TPropertyDictionaryItem[]>` -- the items are cloned and enriched.
+### Value Setting
 
-## Recipe: Rendering a Dynamic Property Form
+Each strategy's `set()` writes to `property.values`:
 
-```vue
-<script setup lang="ts">
-import { useDynamicProperties, useLanguages } from '@vc-shell/framework';
-import { ref, watch } from 'vue';
-
-const { currentLocale } = useLanguages();
-const { loading, loadDictionaries, getPropertyValue, setPropertyValue } =
-  useDynamicProperties(searchDictionaryItems, PropertyValue, PropertyDictionaryItem);
-
-const properties = ref<Property[]>([]);
-
-// Display values, keyed by property ID
-function displayValue(property: Property) {
-  return getPropertyValue(property, currentLocale.value);
-}
-
-// Handle value change from a form input
-async function onValueChange(property: Property, newValue: string) {
-  if (property.dictionary) {
-    const dictItems = await loadDictionaries(property.id!, '', currentLocale.value);
-    setPropertyValue({
-      property,
-      value: newValue,
-      dictionary: dictItems ?? [],
-      locale: currentLocale.value,
-    });
-  } else {
-    setPropertyValue({
-      property,
-      value: newValue,
-      locale: currentLocale.value,
-    });
-  }
-}
-</script>
-```
+- **Empty values are cleaned up automatically** via `cleanEmptyValues()`. When user clears a field, scaffolding objects are removed and `property.values` becomes `[]`. This prevents false modification detection in `useBladeForm`.
+- **Multilanguage cleanup**: Only the value for the current locale is removed; other locales are preserved.
+- **Dictionary**: Expands `localizedValues` into per-locale value entries.
 
-## Recipe: Dictionary Property with Search-as-You-Type
+### Empty Value Cleanup (cleanEmptyValues)
 
-```vue
-<script setup lang="ts">
-import { useDynamicProperties } from '@vc-shell/framework';
-import { ref } from 'vue';
+When `setPropertyValue` receives an empty value (`""`, `null`, `undefined`), it cleans up `property.values` instead of leaving scaffolding objects:
 
-const { loadDictionaries } = useDynamicProperties(/* ... */);
+```
+Before: values: [{ value: "", languageCode: "en", propertyId: "abc", ... }]
+After:  values: []
+```
 
-const dictOptions = ref<PropertyDictionaryItem[]>([]);
+This ensures that `useBladeForm`'s deep comparison correctly detects "no change" when user clears a field that was originally empty.
 
-async function onDictionarySearch(property: Property, keyword: string, locale: string) {
-  const items = await loadDictionaries(property.id!, keyword, locale);
-  dictOptions.value = items ?? [];
-}
-</script>
+## Recipe: With VcDynamicProperty
 
+```vue
 <template>
-  <VcSelect
-    :options="dictOptions"
-    option-value="id"
-    option-label="value"
-    @search="(keyword) => onDictionarySearch(property, keyword, currentLocale)"
-    @update:model-value="(val) => onValueChange(property, val)"
+  <VcDynamicProperty
+    v-for="property in properties"
+    :key="property.id"
+    :property="property"
+    :model-value="getPropertyValue(property, currentLocale)"
+    :options-getter="loadDictionaries"
+    :measurements-getter="loadMeasurements"
+    :current-language="currentLocale"
+    :value-type="property.valueType ?? ''"
+    :dictionary="property.dictionary"
+    :multivalue="property.multivalue"
+    :multilanguage="property.multilanguage"
+    @update:model-value="(ev) => setPropertyValue({ property, ...ev })"
   />
 </template>
+
+<script setup lang="ts">
+import { useDynamicProperties } from "@vc-shell/framework";
+
+const { getPropertyValue, setPropertyValue, loadDictionaries, loadMeasurements } =
+  useDynamicProperties({
+    searchDictionary: searchDictionaryItems,
+    searchMeasurements: searchMeasurementItems,
+  });
+</script>
 ```
 
 ## Tips
 
-- **`setPropertyValue` mutates the property in place.** Unlike `useAssets` which returns new arrays, this composable modifies `property.values` directly. This is by design because dynamic properties are typically part of a larger entity object that gets saved as a whole.
-- **Always pass `dictionary` when setting dictionary values.** Without the dictionary items, the composable cannot resolve `valueId` to the correct alias and localized values. Omitting it results in incomplete value entries.
-- **Empty value handling depends on `initialProp`.** When the user clears a field, the behavior differs based on whether the property originally had a value. If it did, clearing sets `values: []` (explicit empty). If it was always empty, a placeholder value entry is preserved. This distinction matters for the platform's diff/save logic.
-- **Boolean properties always have a value entry.** Unlike other types where clearing removes the value, boolean properties always maintain a value entry (with `value: false`). This ensures checkboxes render correctly.
-- **The composable is generic but not abstract.** You must pass concrete constructor classes, not interfaces. The constructors are called with `new` to create value and dictionary item instances.
+- **`setPropertyValue` mutates the property in place.** `property.values` is modified directly. This is by design because dynamic properties are typically part of a larger entity object saved as a whole.
+- **Always pass `dictionary` when setting dictionary values.** Without dictionary items, the composable cannot resolve `valueId` to the correct alias and localized values.
+- **Boolean properties always have a value entry.** Unlike other types where clearing removes the value, boolean properties maintain a value entry (`value: false`). This ensures checkboxes render correctly.
+- **No class constructors needed.** Values are created as plain objects via `createValue()`. No factory classes required.
+
+## File Structure
+
+```
+useDynamicProperties/
+  index.ts              — composable entry point (~60 lines)
+  types.ts              — all interfaces
+  utils.ts              — isEmptyValue, createValue, cleanEmptyValues, type guards
+  strategies/
+    index.ts            — resolveStrategy() registry
+    types.ts            — PropertyValueStrategy interface
+    regular.ts          — ShortText, LongText, Number, Integer, DateTime
+    boolean.ts          — Boolean
+    dictionary.ts       — Dictionary (all multi/single × language/value)
+    measure.ts          — Measure
+    color.ts            — Color
+```
 
 ## Related
 
-- [useLanguages](../useLanguages/useLanguages.docs.md) -- locale management for multilanguage property rendering
-- `IBaseProperty`, `IBasePropertyValue` -- base interfaces defined in the composable file
-- `PropertyValue`, `PropertyDictionaryItem` from `@core/api/platform` -- concrete types for the standard platform
+- [useBladeForm](../useBladeForm/useBladeForm.docs.md) — form state management that uses `semanticEqual` for modification detection. `cleanEmptyValues` ensures compatibility.
+- [VcDynamicProperty](../../../../ui/components/organisms/vc-dynamic-property/vc-dynamic-property.docs.md) — UI component that renders dynamic properties

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

@@ -1,6 +1,6 @@
 # useSlowNetworkDetection
 
-Detects slow network conditions and shows a persistent warning notification so users know why the UI is unresponsive. Two detection channels work together: a **proactive** channel reads `navigator.connection.effectiveType` to catch weak connections before any request is made, and a **reactive** channel flags API requests that have been pending for more than 5 seconds. The notification auto-dismisses with a 3-second delay after conditions clear, preventing flicker. When the browser goes fully offline, the slow-network notification is suppressed in favor of the existing offline notification from `useConnectionStatus`.
+Detects slow network conditions and shows a persistent warning notification so users know why the UI is unresponsive. Two detection channels work together: a **proactive** channel reads `navigator.connection.effectiveType` to catch weak connections before any request is made, and a **reactive** channel flags API requests that have been pending for more than 10 seconds. The notification auto-dismisses with a 3-second delay after conditions clear, preventing flicker. When the browser goes fully offline, the slow-network notification is suppressed in favor of the existing offline notification from `useConnectionStatus`.
 
 Like `useConnectionStatus`, this is a module-level singleton — calling it from multiple components shares the same state and listeners.
 
@@ -41,14 +41,14 @@ const { isSlowNetwork } = useSlowNetworkDetection();
 | Property | Type | Description |
 |---|---|---|
 | `isSlowNetwork` | `Readonly<Ref<boolean>>` | `true` when the network is slow (either channel active). Read-only. |
-| `trackRequest` | `(id: string) => void` | Start tracking a request. If it isn't untracked within 5 s, it counts as slow. |
+| `trackRequest` | `(id: string) => void` | Start tracking a request. If it isn't untracked within 10 s, it counts as slow. |
 | `untrackRequest` | `(id: string) => void` | Stop tracking a request. Cancels the timer or decrements the slow count. |
 
 ### Constants
 
 | Name | Value | Purpose |
 |---|---|---|
-| `SLOW_REQUEST_THRESHOLD_MS` | `5000` | Time before a pending request is considered slow |
+| `SLOW_REQUEST_THRESHOLD_MS` | `10000` | Time before a pending request is considered slow |
 | `DISMISS_DELAY_MS` | `3000` | Delay before hiding the notification after recovery |
 | `SLOW_EFFECTIVE_TYPES` | `["slow-2g", "2g"]` | Connection types flagged as slow |
 
@@ -60,7 +60,7 @@ On first call, the composable checks `navigator.connection.effectiveType` (Netwo
 
 ### Channel 2: Request timers (reactive)
 
-The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequest(id)` before every `/api/*` request and `untrackRequest(id)` in the `finally` block. Each tracked request gets a 5-second timer. If the response arrives in time, the timer is cancelled. If not, `isSlowNetwork` becomes `true` and stays `true` until all slow requests complete.
+The fetch interceptor in `framework/core/interceptors/index.ts` calls `trackRequest(id)` before every `/api/*` request and `untrackRequest(id)` in the `finally` block. Each tracked request gets a 10-second timer. If the response arrives in time, the timer is cancelled. If not, `isSlowNetwork` becomes `true` and stays `true` until all slow requests complete.
 
 ### Notification lifecycle
 

package/runtime/knowledge/docs/core/utilities/thumbnail/thumbnail.docs.md

@@ -0,0 +1,116 @@
+# Thumbnail URL Utility
+
+Transforms full-size image URLs into thumbnail variants by appending size suffixes before the file extension. VirtoCommerce backend generates thumbnails automatically with these suffixes.
+
+## When to Use
+
+- Use in any component that displays images at a known size smaller than the original
+- Reduces bandwidth and improves page load time significantly
+- Especially important for image lists (tables, galleries, cards)
+
+## Available Sizes
+
+### Named Presets
+
+| Preset | Use Case |
+|--------|----------|
+| `sm` | Small icons, table cells, avatar thumbnails |
+| `md` | Medium previews, cards |
+| `lg` | Large previews, hero images |
+
+### Pixel Sizes
+
+| Size | Pixels | Use Case |
+|------|--------|----------|
+| `64x64` | 64px | Table cells, tiny thumbnails |
+| `128x128` | 128px | Small tiles, list items |
+| `168x168` | 168px | Medium tiles |
+| `216x216` | 216px | Gallery tiles (md) |
+| `348x348` | 348px | Large gallery tiles |
+
+## API
+
+### `getThumbnailUrl(url, size?)`
+
+Transforms an image URL by inserting a size suffix before the file extension.
+
+```ts
+import { getThumbnailUrl } from "@core/utilities/thumbnail";
+
+getThumbnailUrl("https://cdn.example.com/photo.jpg", "sm")
+// → "https://cdn.example.com/photo_sm.jpg"
+
+getThumbnailUrl("https://cdn.example.com/photo.jpg", "128x128")
+// → "https://cdn.example.com/photo_128x128.jpg"
+
+getThumbnailUrl("https://cdn.example.com/photo.jpg")
+// → "https://cdn.example.com/photo.jpg" (unchanged)
+
+getThumbnailUrl(undefined, "sm")
+// → undefined
+```
+
+**Parameters:**
+- `url` — Original image URL (string or undefined)
+- `size` — Thumbnail size preset or pixel dimensions (optional)
+
+**Returns:** Transformed URL, or original URL if size not specified
+
+### `getBestThumbnailSize(displaySize)`
+
+Maps a CSS pixel display size to the best-fit thumbnail preset. Picks the smallest thumbnail that is >= the display size.
+
+```ts
+import { getBestThumbnailSize } from "@core/utilities/thumbnail";
+
+getBestThumbnailSize(48)   // → "64x64"
+getBestThumbnailSize(96)   // → "128x128"
+getBestThumbnailSize(200)  // → "216x216"
+getBestThumbnailSize(500)  // → "lg"
+```
+
+## Usage in Components
+
+### VcImage
+
+```vue
+<VcImage
+  :src="product.imgSrc"
+  thumbnail-size="sm"
+  size="s"
+/>
+```
+
+### VcGallery
+
+Gallery auto-maps `size` prop to thumbnail size. Override with `thumbnailSize`:
+
+```vue
+<!-- Auto: sm→128x128, md→216x216, lg→348x348 -->
+<VcGallery :images="images" size="md" />
+
+<!-- Explicit override -->
+<VcGallery :images="images" thumbnail-size="128x128" />
+```
+
+Gallery preview uses `64x64` for the thumbnail strip and full-size for the main image automatically.
+
+### VcDataTable (CellImage)
+
+Table image cells use `sm` thumbnail by default — no action needed.
+
+## Types
+
+```ts
+type ThumbnailPreset = "sm" | "md" | "lg";
+type ThumbnailPixelSize = "64x64" | "128x128" | "168x168" | "216x216" | "348x348";
+type ThumbnailSize = ThumbnailPreset | ThumbnailPixelSize;
+```
+
+## Notes
+
+- The utility only transforms the URL — the backend must have generated the thumbnail for the URL to resolve
+- If a thumbnail doesn't exist on the server, the browser will show a broken image. Ensure your asset pipeline generates all required sizes.
+- The suffix is inserted before the file extension: `photo.jpg` → `photo_sm.jpg`
+- URLs without a file extension are returned unchanged
+- Already-suffixed URLs are not double-transformed

package/runtime/knowledge/docs/shell/components/change-password-button/change-password-button.docs.md

@@ -91,4 +91,4 @@ export default {
 - [SettingsMenu](../settings-menu/settings-menu.docs.md) -- parent container
 - [SettingsMenuItem](../settings-menu-item/settings-menu-item.docs.md) -- base menu item used internally
 - [LogoutButton](../logout-button/logout-button.docs.md) -- sibling account action
-- [ChangePasswordPage](../../pages/ChangePasswordPage/change-password-page.docs.md) -- full-page variant for expired passwords
+- [ChangePasswordPage](../../auth/ChangePasswordPage/change-password-page.docs.md) -- full-page variant for expired passwords

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

@@ -28,6 +28,7 @@ An image display component with predefined sizes, aspect ratio control, and a pl
 | `clickable` | `boolean` | `false` | Makes the image interactive with cursor and click event |
 | `emptyIcon` | `string` | `"lucide-image"` | Icon shown when `src` is empty |
 | `alt` | `string` | — | Accessible alt text |
+| `thumbnailSize` | `ThumbnailSize` | — | Load a thumbnail variant instead of full-size image. Values: `"sm"`, `"md"`, `"lg"`, `"64x64"`, `"128x128"`, `"168x168"`, `"216x216"`, `"348x348"` |
 
 ## Size Reference
 

package/runtime/knowledge/docs/ui/components/molecules/vc-image-tile/vc-image-tile.docs.md

@@ -40,6 +40,7 @@ function deleteImage() { /* remove from list */ }
 | `name` | `string` | — | File name displayed in the tray |
 | `imageFit` | `"contain" \| "cover"` | `"contain"` | How the image fits within the tile |
 | `actions` | `VcImageTileActions` | — | Which built-in action buttons to show |
+| `thumbnailSize` | `ThumbnailSize` | — | Load a thumbnail variant instead of full-size image |
 
 ## VcImageTileActions Interface
 

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

@@ -62,7 +62,7 @@ A blade has four visual zones, rendered top-to-bottom:
 |--------------------------------------|
 |  [Save] [Delete] [Refresh]  [More >] |  <-- Toolbar
 |--------------------------------------|
-|  ** Unsaved changes banner **        |  <-- Status Banners
+|  ** Status banners (stacked) **      |  <-- Status Banners
 |--------------------------------------|
 |                                      |
 |         Content (default slot)       |  <-- Content Area
@@ -74,7 +74,7 @@ A blade has four visual zones, rendered top-to-bottom:
 
 **Toolbar** -- Action buttons from the `toolbarItems` prop. Overflow items automatically collapse into a "More" dropdown (via `ResizeObserver`).
 
-**Status Banners** -- Yellow banner when `modified` is `true`; red banner when the blade has an error (set via `setError()`).
+**Status Banners** -- Unified, priority-sorted banner area. System banners: yellow when `modified` is `true`, red when the blade has an error (via `setError()`). Custom banners can be added programmatically via `useBlade().addBanner()` — see [useBlade docs](../../../core/composables/useBlade/useBlade.docs.md#banner-management).
 
 **Content Area** -- The `default` slot. Scrolls independently of header and toolbar.
 
@@ -399,6 +399,31 @@ import { useBeforeUnload } from "@vc-shell/framework";
 useBeforeUnload(hasChanges);  // Browser tab close warning
 ```
 
+## Custom Banners
+
+Add informational, warning, or success banners to a blade programmatically. Banners appear between the header and toolbar, sorted by severity.
+
+```vue
+<script setup lang="ts">
+import { useBlade } from "@vc-shell/framework";
+
+const { addBanner, removeBanner, clearBanners } = useBlade();
+
+// Info banner (e.g. read-only mode)
+addBanner({ variant: "info", message: "This record is read-only" });
+
+// Dismissible warning with action
+addBanner({
+  variant: "warning",
+  message: "License expires in 7 days",
+  dismissible: true,
+  action: { label: "Renew", handler: () => openRenewal() },
+});
+</script>
+```
+
+Four variants are available: `danger`, `warning`, `info`, `success`. System banners (error and unsaved changes) are always present and cannot be removed by `clearBanners()`. For the full API reference, see [useBlade — Banner Management](../../../core/composables/useBlade/useBlade.docs.md#banner-management).
+
 ## Blade Width Control
 
 ```vue

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

@@ -13,17 +13,21 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
+| `layout` | `"filmstrip" \| "grid"` | `"filmstrip"` | Layout mode — filmstrip shows a single scrollable row with expand/collapse; grid shows the classic multi-row auto-fill layout. |
+| `label` | `string` | `undefined` | Label text displayed in the gallery header. |
+| `required` | `boolean` | `false` | Shows a required indicator (`*`) on the label. |
 | `images` | `ICommonAsset[]` | `[]` | Array of image assets to display. |
 | `disabled` | `boolean` | `false` | Disables all interactive actions. |
 | `multiple` | `boolean` | `false` | Allow selecting multiple files in upload dialog. |
-| `loading` | `boolean` | `false` | Shows a loading spinner on the upload zone. |
+| `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. |
 | `name` | `string` | `"Gallery"` | Field name for validation messages. |
 | `accept` | `string` | `undefined` | Accepted file extensions. |
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tile size preset. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Tile size preset. Sizes are smaller on mobile. |
 | `gap` | `number` | `8` | Gap between tiles in pixels. |
 | `imagefit` | `"contain" \| "cover"` | `"contain"` | How images fit within tiles. |
+| `thumbnailSize` | `ThumbnailSize` | auto from `size` | Thumbnail size for tile images. Auto-mapped: sm→128x128, md→216x216, lg→348x348. Preview thumbnails use 64x64. |
 
 ## Events
 
@@ -44,20 +48,24 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 
 ## Features
 
-- **Drag-and-drop reorder** -- Drag tiles to reorder. Emits `sort` with the new array. The dragged tile shows a ghost preview during the drag operation.
-- **External file drop** -- Drop files from the OS onto the gallery to upload. The entire gallery acts as a drop target with visual feedback.
-- **Lightbox preview** -- Click a tile to open a full-screen preview carousel. Navigate between images with arrow keys or swipe gestures.
-- **Responsive grid** -- Auto-fill grid adapts to container width using CSS grid with `auto-fill` and `minmax()`.
-- **Per-tile actions** -- Each tile shows preview, edit, and remove buttons on hover. Disable individual actions via the `itemActions` prop.
+- **Filmstrip layout (default)** -- Single-row scrollable strip powered by Swiper. Navigate with arrows, mouse wheel, or swipe. Click "Expand (N)" to show all images in a grid. "Collapse" returns to filmstrip.
+- **Grid layout** -- Classic auto-fill grid that wraps images into multiple rows. Set `layout="grid"` to use this mode.
+- **Drag-and-drop reorder** -- Drag tiles by the grip handle to reorder (powered by SortableJS). Works on both desktop and touch devices. In filmstrip mode, dragging to the edge auto-scrolls the strip. Emits `sort` with the new array.
+- **External file drop** -- Drop files from the OS onto the gallery to upload. The dashed border acts as a visual drop zone indicator (desktop only). A full overlay appears during drag-over.
+- **Fullscreen preview** -- Click the preview button to open a fullscreen carousel. Swipe or use arrow keys to navigate. Thumbnail strip at the bottom syncs with the main image.
+- **Per-tile actions** -- Each tile shows preview, edit, and remove buttons. On desktop: visible on hover. On mobile: visible on tap. Tile name is shown in the top bar alongside the drag handle.
+- **Loading state** -- When `loading` is true, a pulsing border and spinner overlay appear on the gallery. Upload button is disabled. Swiper navigation is frozen.
+- **Mobile responsive** -- Smaller tile sizes, no drag-and-drop hints, no dashed borders, compact action buttons, tap-to-reveal overlays. Uses `useResponsive` throughout.
+- **Lazy loading** -- Images use native `loading="lazy"` for deferred loading.
 
 ## Basic Usage
 
 ```vue
 <VcGallery
+  label="Product Images"
+  required
   :images="product.images"
-  size="md"
   imagefit="cover"
-  :item-actions="{ preview: true, edit: true, remove: true }"
   @upload="handleUpload"
   @sort="handleSort"
   @edit="handleEdit"
@@ -65,6 +73,31 @@ A responsive multi-image gallery with drag-and-drop reorder, file upload, lightb
 />
 ```
 
+## Filmstrip Layout (Default)
+
+```vue
+<VcGallery
+  label="Images"
+  :images="product.images"
+  imagefit="cover"
+  @upload="handleUpload"
+  @sort="handleSort"
+  @remove="handleRemove"
+/>
+```
+
+## Classic Grid Layout
+
+```vue
+<VcGallery
+  layout="grid"
+  label="Attachments"
+  :images="product.images"
+  @upload="handleUpload"
+  @sort="handleSort"
+/>
+```
+
 ## Recipe: Product Image Gallery in a Blade
 
 ```vue
@@ -99,6 +132,8 @@ function handleRemove(image: ICommonAsset) {
 <template>
   <VcBlade title="Product Images">
     <VcGallery
+      label="Product Images"
+      required
       :images="images"
       multiple
       accept=".jpg,.png,.webp"
@@ -152,20 +187,24 @@ function handleRemove(image: ICommonAsset) {
 
 ## Tips
 
-- The `size` prop controls tile dimensions: `"sm"` is good for compact grids (e.g., thumbnails in a sidebar), `"md"` is the standard, and `"lg"` works well for hero image management.
+- The `size` prop controls tile dimensions: `"sm"` is good for compact grids (e.g., thumbnails in a sidebar), `"md"` is the standard, and `"lg"` works well for hero image management. Tiles are automatically smaller on mobile.
 - Use `imagefit="cover"` for photo galleries where cropping is acceptable, and `"contain"` for logos or icons where the full image must be visible.
-- The upload zone tile always appears at the end of the grid when the gallery is not disabled. It accepts both click and drag-and-drop interactions.
+- The filmstrip layout is ideal for blades where vertical space is limited. Users can expand to see all images or scroll horizontally. The classic grid layout is better for dedicated media management pages.
+- Use the `label` prop to display a header label integrated with the upload button. Add `required` to show a required indicator.
 - The `startingSortOrder` parameter in the `upload` event tells you where the new files should be inserted in the sort order. Use it to maintain correct ordering when appending new images.
+- On desktop, reorder by dragging the grip handle icon. In filmstrip mode, dragging to the strip edge auto-scrolls to reveal more tiles.
+- On mobile, tap a tile to reveal action buttons and the image name. Drag-and-drop hints and dashed borders are hidden automatically.
 
 ## Accessibility
 
 - Tiles are keyboard-navigable with Tab and action buttons are focusable
-- Lightbox preview supports keyboard navigation (arrow keys, Escape to close)
-- The upload zone is accessible via keyboard (Enter/Space to open file picker)
-- Drag-and-drop reorder requires mouse/touch; provide an alternative reorder mechanism for keyboard-only users if needed
+- Fullscreen preview supports keyboard navigation (arrow keys, Escape to close) and swipe gestures
+- The upload button in the header is keyboard-accessible
+- On mobile, tile actions are revealed via tap with click-outside to dismiss
 
 ## Related Components
 
 - **VcImageUpload** -- single-image upload component
-- **VcImageTile** -- the internal tile component used for each image
-- **VcLabel** / **VcHint** -- use alongside VcGallery for field labeling
+- **VcImageTile** -- the internal tile component used 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/core/composables/useGlobalSearch/useGlobalSearch.docs.md

@@ -1,146 +0,0 @@
-# useGlobalSearch
-
-Provides access to the global search service state: per-blade search visibility, search queries, and methods to toggle/close search. The service maintains a map of blade IDs to search state, allowing each blade in the stack to have its own independent search input. The state is shared through Vue's provide/inject system and automatically cleaned up when the scope is disposed.
-
-Also exports `provideGlobalSearch()` for framework-level initialization.
-
-## When to Use
-
-- In blade toolbars or headers to toggle and read the search input visibility for a specific blade
-- To programmatically set or read the search query for a specific blade (e.g., from a URL parameter or external trigger)
-- To integrate search with the blade toolbar's search icon button
-- When NOT to use: for table-level filtering within a blade, use VcDataTable's built-in search header. Global search is for blade-level search that affects the entire blade's content.
-
-## Quick Start
-
-```vue
-<script setup lang="ts">
-import { useGlobalSearch } from '@vc-shell/framework';
-import { computed, watch } from 'vue';
-
-const props = defineProps<{ bladeId: string }>();
-const { isSearchVisible, searchQuery, toggleSearch, setSearchQuery, closeSearch } = useGlobalSearch();
-
-// Reactive accessors scoped to this blade
-const isVisible = computed(() => isSearchVisible.value[props.bladeId] ?? false);
-const query = computed(() => searchQuery.value[props.bladeId] ?? '');
-
-// React to search query changes
-watch(query, (newQuery) => {
-  if (newQuery.length >= 2) {
-    fetchResults(newQuery);
-  }
-});
-
-function onSearchToggle() {
-  toggleSearch(props.bladeId);
-}
-
-function onSearchClose() {
-  closeSearch(props.bladeId);
-}
-</script>
-
-<template>
-  <div>
-    <VcButton icon="fas fa-search" @click="onSearchToggle" />
-    <VcInput
-      v-if="isVisible"
-      :model-value="query"
-      placeholder="Search..."
-      @update:model-value="(val) => setSearchQuery(bladeId, val)"
-      @keydown.escape="onSearchClose"
-    />
-  </div>
-</template>
-```
-
-## API
-
-### Parameters
-
-None.
-
-### Returns (`GlobalSearchState`)
-
-| Property / Method | Type | Description |
-|-------------------|------|-------------|
-| `isSearchVisible` | `Ref<Record<string, boolean>>` | Map of blade IDs to search visibility state. Access via `isSearchVisible.value[bladeId]`. |
-| `searchQuery` | `Ref<Record<string, string>>` | Map of blade IDs to current search query strings. Access via `searchQuery.value[bladeId]`. |
-| `toggleSearch` | `(bladeId: string) => void` | Toggles search visibility for a blade. If visible, hides it (and clears the query). If hidden, shows it. |
-| `setSearchQuery` | `(bladeId: string, query: string) => void` | Sets the search query for a blade. Does not affect visibility. |
-| `closeSearch` | `(bladeId: string) => void` | Hides the search input for a blade and clears the query. |
-
-### Additional Exports
-
-| Export | Description |
-|--------|-------------|
-| `provideGlobalSearch()` | Creates and provides the global search service. Idempotent -- returns existing service if already provided. Cleans up all state on scope disposal. |
-
-## How It Works
-
-The service is a simple reactive state container with two `Ref<Record<string, ...>>` maps. Each blade ID is a key in these maps. This design means:
-
-1. **Blades are isolated**: Each blade has its own search visibility and query. Opening search in one blade does not affect others in the stack.
-2. **Lazy initialization**: A blade's entry in the map is created on first `toggleSearch` or `setSearchQuery` call. Reading a non-existent key returns `undefined`, which the consumer treats as `false`/empty.
-3. **Cleanup**: When `provideGlobalSearch()` scope is disposed (e.g., app unmount), both maps are cleared.
-
-## Recipe: Toolbar Search Button with Badge Indicator
-
-```vue
-<script setup lang="ts">
-import { useGlobalSearch } from '@vc-shell/framework';
-import { computed } from 'vue';
-
-const props = defineProps<{ bladeId: string }>();
-const { isSearchVisible, searchQuery, toggleSearch } = useGlobalSearch();
-
-const hasActiveSearch = computed(() => {
-  const query = searchQuery.value[props.bladeId];
-  return query != null && query.length > 0;
-});
-</script>
-
-<template>
-  <VcButton
-    :icon="hasActiveSearch ? 'fas fa-search-plus' : 'fas fa-search'"
-    :variant="hasActiveSearch ? 'primary' : 'ghost'"
-    @click="toggleSearch(bladeId)"
-  />
-</template>
-```
-
-## Recipe: Pre-Populating Search from URL Query Parameter
-
-```vue
-<script setup lang="ts">
-import { useGlobalSearch } from '@vc-shell/framework';
-import { useRoute } from 'vue-router';
-import { onMounted } from 'vue';
-
-const props = defineProps<{ bladeId: string }>();
-const route = useRoute();
-const { setSearchQuery, toggleSearch } = useGlobalSearch();
-
-onMounted(() => {
-  const urlQuery = route.query.search as string | undefined;
-  if (urlQuery) {
-    setSearchQuery(props.bladeId, urlQuery);
-    toggleSearch(props.bladeId); // make the search input visible
-  }
-});
-</script>
-```
-
-## Tips
-
-- **`toggleSearch` clears the query when hiding.** This is by design -- when the user closes the search, the query is reset. If you need to preserve the query across toggle cycles, store it separately.
-- **Use blade ID, not component instance ID.** The blade ID comes from the blade descriptor and is stable across re-renders. Using a component's `uid` would break if the component is recreated.
-- **State is not persisted.** Unlike sidebar state, search state is in-memory only. Refreshing the page clears all search queries. Use URL query parameters if you need persistence.
-- **Calling outside VcApp throws.** Like all provide/inject composables in the framework, `useGlobalSearch()` throws an `InjectionError` if the service has not been provided.
-
-## Related
-
-- VcDataTable search header -- table-level filtering built into the data table (different from global search)
-- [useToolbar](../useToolbar/) -- toolbar service for blade action buttons (often includes a search toggle button)
-- `framework/core/services/global-search-service.ts` -- underlying service implementation

package/runtime/knowledge/docs/shell/pages/ChangePasswordPage/change-password-page.docs.md

@@ -1,102 +0,0 @@
-# ChangePasswordPage
-
-Change password page with current, new, and confirm password fields. Supports a `forced` mode for expired passwords that displays an info banner and is triggered by post-login redirect. This full-page variant is used when the user must change their password before accessing the application (e.g., expired password policy). For voluntary password changes from within the app, the `ChangePasswordButton` in the settings menu opens a popup instead.
-
-## When to Use
-
-- When a signed-in user wants to change their password (full-page flow)
-- In `forced` mode after login when the user's password has expired
-- The standard vc-shell routing maps `/change-password` to this page
-
-## Basic Usage
-
-```vue
-<template>
-  <ChangePassword />
-</template>
-
-<!-- Forced mode (expired password) -->
-<template>
-  <ChangePassword forced />
-</template>
-```
-
-With custom branding:
-
-```vue
-<template>
-  <ChangePassword
-    forced
-    logo="/assets/my-company-logo.svg"
-    background="/assets/custom-background.jpg"
-  />
-</template>
-```
-
-## Key Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `forced` | `boolean` | `false` | Show expired-password info banner and adjusted title |
-| `logo` | `string` | - | Override logo image URL |
-| `background` | `string` | - | Custom background image URL |
-
-## Recipe: Router Configuration with Forced Mode
-
-Set up the route so the login page can redirect here when the password is expired:
-
-```ts
-import ChangePassword from "@vc-shell/framework/shared/pages/ChangePasswordPage";
-
-const routes = [
-  {
-    path: "/change-password",
-    name: "ChangePassword",
-    component: ChangePassword,
-    props: (route) => ({
-      forced: route.query.forced === "true",
-    }),
-  },
-];
-```
-
-In the login flow, redirect when the user's password has expired:
-
-```ts
-async function handleLogin() {
-  const result = await signIn(username.value, password.value);
-  if (result.passwordExpired) {
-    router.push({ name: "ChangePassword", query: { forced: "true" } });
-  } else {
-    router.push("/");
-  }
-}
-```
-
-## Features
-
-- **Real-time password policy validation**: Uses `useUserManagement().validatePassword` to check the new password against the platform's policy as the user types (minimum length, required uppercase, lowercase, digits, special characters)
-- **Equal password detection**: Shows a specific "Equal-passwords" error when the new password matches the current password, without making an API call
-- **Confirm-password mismatch detection**: Validates that the new password and confirm password fields match
-- **Forced mode banner**: When `forced` is `true`, displays an info banner explaining that the password has expired and must be changed
-- **Cancel behavior**: Cancel button signs out the user and redirects to `/login`
-- **Success redirect**: On successful password change, redirects to `/` (main application)
-
-## Details
-
-- **Auth layout**: Renders inside `VcAuthLayout`, providing the centered card design with logo and background.
-- **Password policy**: The validation rules are fetched from the platform API and include configurable requirements (minimum length, character classes, etc.). The component displays these rules as a checklist.
-- **Forced vs voluntary**: In forced mode (`forced=true`), the page title changes to reflect the expired password scenario, and an info banner explains why the change is required. The form fields and behavior are otherwise identical.
-- **Sign-out on cancel**: If the user cancels during a forced password change, they are signed out. This prevents access to the application with an expired password.
-
-## Tips
-
-- The `forced` prop is typically set via a route query parameter, not hardcoded. The login page detects expired passwords and redirects with the appropriate flag.
-- Password policy validation runs on keyup, providing immediate feedback. The submit button is disabled until all policy requirements are met and the passwords match.
-- This page is distinct from the `ChangePasswordButton` popup. The page is for full-screen flow (forced changes), while the popup is for voluntary in-app password changes.
-
-## Related Components
-
-- **VcAuthLayout** - The underlying centered card layout
-- **LoginPage** - Redirects here when `user.passwordExpired` is true
-- **ChangePasswordButton** - Settings menu popup variant for voluntary password changes