@dxtmisha/wiki 0.39.8 → 0.57.0

package/dist/{wikiDescriptions-Cv4WzSNL.js → wikiDescriptions-7XaHU3Yk.js}

@@ -58,6 +58,35 @@ var e = [
 			description: "\nCollapsible container for progressive disclosure. Toggles content visibility to manage space and cognitive load. Use for FAQs, grouped settings, hiding secondary info, or compact dashboards.\nHeader is based on a Cell component and supports label, description, and icon. Features an auto-rotating arrow indicator and smooth height transitions via MotionTransform.\nBuilt-in ARIA support and keyboard navigation (Space/Enter). Controlled primarily via v-model:open. Customizable with divider and header attributes through cellAttrs.\n    "
 		}
 	},
+	{
+		name: "Area",
+		description: {
+			en: "Component for rendering content based on the current area context",
+			ru: "Компонент для отображения контента в зависимости от текущего контекста области"
+		},
+		possibilities: {
+			en: [
+				"automatic slot selection based on injected area value",
+				"fallback to a default area if no injection is found",
+				"supports nested areas and context inheritance",
+				"renders default slot if no specific area slot matches"
+			],
+			ru: [
+				"автоматический выбор слота на основе внедренного значения области",
+				"возврат к области по умолчанию, если внедрение не найдено",
+				"поддержка вложенных областей и наследования контекста",
+				"отображение слота по умолчанию, если ни один специфический слот области не подходит"
+			]
+		},
+		import: [],
+		render: "\n    <DesignComponent v-bind=\"args\">\n      <template #header>Header Content (from area-default)</template>\n      <template #footer>Footer Content</template>\n      <template #default>Default Content</template>\n    </DesignComponent>\n  ",
+		stories: [],
+		documentation: {
+			body: "\n<StorybookDescriptions componentName={'Area'} type={'area'}/>\n    ",
+			slots: "\n<StorybookDescriptions componentName={'Area'} type={'slot'}/>\n    "
+		},
+		ai: { description: "\nA utility component that acts as a dynamic slot switcher based on an \"area\" context.\nIt retrieves the current area value from the injection context (UI_AREA_VALUE) or uses the 'areaDefault' prop.\nIt then renders the slot that matches the area name. If no matching slot is found, it falls back to the 'default' slot.\nThis is particularly useful for building layouts where different components need to render different content depending on where they are placed (e.g., in a header, footer, or side panel).\n    " }
+	},
 	{
 		name: "Actions",
 		description: {
@@ -748,6 +777,70 @@ var e = [
 		},
 		ai: { description: "\nWrapper component for managing collections of Chip elements based on an array of data. Streamlines the creation of filter sets, choice groups, and tag lists by automating iteration and selection logic.\nFeatures support for single and multiple selection modes, shared chip attributes (via chipAttrs), and icon visibility control. Includes built-in data binding for selected values and @click event propagation.\nControlled via the list prop for data and v-model:selected for state. Use for dynamic filtering interfaces, selecting multiple categories, or building interactive tag lists from API data.\n    " }
 	},
+	{
+		name: "ClientOnly",
+		description: {
+			en: "Component for managing rendering exclusively on the client side, essential for SSR compatibility",
+			ru: "Компонент для управления рендерингом исключительно на стороне клиента, необходим для совместимости с SSR"
+		},
+		possibilities: {
+			en: [
+				"prevents hydration mismatch errors in SSR/SSG environments",
+				"render client-side only components (e.g. charts, maps)",
+				"toggleable via \"clientOnly\" property",
+				"supports default slot for the content"
+			],
+			ru: [
+				"предотвращает ошибки рассогласования гидратации в средах SSR/SSG",
+				"рендерит компоненты только для клиента (например, графики, карты)",
+				"переключается через свойство \"clientOnly\"",
+				"поддерживает слот default для контента"
+			]
+		},
+		import: [],
+		render: "\n    <DesignComponent>\n      <h4>Client-Side Content</h4>\n      <p>This block is only visible when the component is mounted in the browser.</p>\n      <p>Use it for components that depend on window, document, or other browser-specific APIs.</p>\n    </DesignComponent>\n  ",
+		stories: [],
+		documentation: {
+			body: "\n<StorybookDescriptions componentName={'ClientOnly'} type={'clientOnly'}/>\n    ",
+			slots: "\n<StorybookDescriptions componentName={'Slot'} type={'default'}/>\n    "
+		},
+		ai: {
+			render: "\n<div :class=\"classDemo.item\">\n  <ClientOnly v-bind=\"args\">\n    <h4>Client-Side Content</h4>\n    <p>This block is only visible when the component is mounted in the browser.</p>\n    <p>Use it for components that depend on window, document, or other browser-specific APIs.</p>\n  </ClientOnly>\n</div>\n    ",
+			description: "\nThe ClientOnly component is a utility designed to ensure that its children are only rendered on the client side.\nThis is particularly useful in Server-Side Rendering (SSR) or Static Site Generation (SSG) contexts where certain components\n(like those relying on browser-only APIs like 'window' or 'document', or complex visualizations) should not be executed or rendered on the server.\nIt works by waiting until the component is mounted in the browser before rendering its content.\nControlled by the 'clientOnly' boolean property (default is true).\n    "
+		}
+	},
+	{
+		name: "Container",
+		description: {
+			en: "A lightweight layout container for centering and constraining content width with configurable horizontal alignment.",
+			ru: "Легковесный компонент-контейнер для центрирования и ограничения ширины контента с настраиваемым горизонтальным выравниванием."
+		},
+		possibilities: {
+			en: [
+				"horizontal alignment with align: left | center | right",
+				"configurable width and horizontal margins via design tokens",
+				"default slot for wrapping arbitrary content",
+				"area context support through the area prop"
+			],
+			ru: [
+				"горизонтальное выравнивание через align: left | center | right",
+				"настройка ширины и горизонтальных отступов через дизайн-токены",
+				"слот default для оборачивания произвольного контента",
+				"поддержка контекста области через свойство area"
+			]
+		},
+		import: [],
+		render: "\n    <DesignComponent v-bind=\"args\">\n      <p>\n        Container helps keep content readable by limiting line length and controlling side spacing.\n      </p>\n      <p>\n        Use it as a base layout wrapper for page sections, forms, and content blocks.\n      </p>\n    </DesignComponent>\n  ",
+		stories: [],
+		documentation: {
+			body: "\n<StorybookDescriptions componentName={'Container'} type={'container'}/>\n    ",
+			slots: "\n<StorybookDescriptions componentName={'Slot'} type={'default'}/>\n    "
+		},
+		ai: {
+			render: "\n<div :class=\"classDemo.item\">\n  <Container v-bind=\"args\">\n    Main content goes here.\n  </Container>\n</div>\n    ",
+			description: "\nLayout wrapper used to constrain content width and manage horizontal spacing in a predictable way.\nSupports alignment options (left, center, right), width tokens, and side margins so page content keeps consistent rhythm across breakpoints.\nUse as a foundational container around sections, forms, and text-heavy blocks to improve readability and layout consistency.\n    "
+		}
+	},
 	{
 		name: "Dialog",
 		description: {
@@ -1143,6 +1236,52 @@ var e = [
 			description: "\nStructural component for organizing related content with a standardized header hierarchy. Acts as a semantic wrapper for subsections or grouping elements within a larger section or card.\nFeatures support for headlines (h4 by default), labels, icons, and descriptions. Inherits all capabilities of the Block component, providing a consistent layout for titles and body content.\nControlled via headline, label, and description props. Use for grouping settings, categorizing information, or breaking down complex forms into logical, titled segments.\n    "
 		}
 	},
+	{
+		name: "Header",
+		description: {
+			en: "Component for displaying headers with icons and additional information",
+			ru: "Компонент для отображения заголовков с иконками и дополнительной информацией"
+		},
+		possibilities: {
+			en: [
+				"support for different HTML tags (h1-h6, div, etc.)",
+				"built-in support for icons and captions",
+				"customizable trailing content via slots",
+				"automatic area value management",
+				"standardized typography and spacing"
+			],
+			ru: [
+				"поддержка различных HTML-тегов (h1-h6, div и т.д.)",
+				"встроенная поддержка иконок и подписей",
+				"настраиваемый правый контент через слоты",
+				"автоматическое управление значением области",
+				"стандартизированная типографика и отступы"
+			]
+		},
+		import: [],
+		stories: [{
+			id: "HeaderBasic",
+			name: {
+				en: "Basic",
+				ru: "Базовые"
+			},
+			template: "\n        <div class=\"wiki-storybook-flex--column\">\n          <DesignComponent label=\"Header Level 1\" tag=\"h1\" />\n          <DesignComponent label=\"Header Level 2\" tag=\"h2\" />\n          <DesignComponent label=\"Header Level 3\" tag=\"h3\" />\n        </div>\n      "
+		}, {
+			id: "HeaderSlots",
+			name: {
+				en: "Slots",
+				ru: "Слоты"
+			},
+			template: "\n        <DesignComponent label=\"Default label\" caption=\"Default caption\">\n          <template #default>Custom label slot</template>\n          <template #caption>Custom caption slot</template>\n          <template #trailing>Trailing slot</template>\n        </DesignComponent>\n      "
+		}],
+		documentation: {
+			body: "\n<StorybookDescriptions componentName={'Header'} type={'header'}/>\n<Canvas of={Component.HeaderBasic}/>\n    ",
+			events: "",
+			expose: "",
+			slots: "\n<Canvas of={Component.HeaderSlots}/>\n<StorybookDescriptions componentName={'Slot'} type={'default'}/>\n<StorybookDescriptions componentName={'Slot'} type={'caption'}/>\n<StorybookDescriptions componentName={'Slot'} type={'trailing'}/>\n    "
+		},
+		ai: { description: "\nComponent for creating structured headers with integrated support for icons and captions.\nAllows flexible control over the HTML tag (h1-h6, div) to maintain proper document hierarchy.\nIncludes automatic area management and support for custom trailing content.\nIdeal for section titles, page headers, or grouped content labeling.\n    " }
+	},
 	{
 		name: "HorizontalScroll",
 		description: {
@@ -2029,6 +2168,49 @@ var e = [
 			description: "\nTop-level structural container designed to wrap the primary content of a view or document. Serves as a semantic root (typically rendering a <main> tag) and establishes the high-level document hierarchy with standardized headers.\nFeatures a comprehensive header structure inherited from the Block component, including support for headlines (h1), labels (page titles), descriptions, and trailing action areas. Automatically manages spacing and layout consistency for page-level navigation and identity.\nControlled via headline, label, and icon props, with dedicated slots for content and actions (#default, #trailing). Use as the foundational wrapper for any route or unique screen to ensure accessibility and consistent information architecture.\n    "
 		}
 	},
+	{
+		name: "PageArea",
+		description: {
+			en: "A structural component that automatically selects and renders appropriate UI blocks (Page, Section, Block, or Group) based on the current nesting level or area context.",
+			ru: "Структурный компонент, который автоматически выбирает и отрисовывает подходящие блоки интерфейса (Page, Section, Block или Group) в зависимости от текущего уровня вложенности или контекста области."
+		},
+		possibilities: {
+			en: [
+				"automatic component switching based on area context",
+				"semantic content organization with consistent structure",
+				"integration with layout zones and hierarchical state",
+				"shorthand for complex page layouts with nested elements"
+			],
+			ru: [
+				"автоматическое переключение компонентов на основе контекста области",
+				"семантическая организация контента с согласованной структурой",
+				"интеграция с зонами макета и иерархическим состоянием",
+				"сокращенная запись для сложных макетов страниц с вложенными элементами"
+			]
+		},
+		import: [],
+		render: "\n      <DesignComponent v-bind=\"args\">\n        <p>\n          The PageArea component is a specialized container designed to structure the content within a specific page or layout region.\n          It provides consistent margins, alignment, and semantic grouping for nested components.\n        </p>\n        <p>\n          It acts as an orchestrator for various UI blocks, allowing developers to define a clear information hierarchy.\n          Whether it's a dashboard overview or a detailed data view, PageArea ensures the layout remains cohesive.\n        </p>\n      </DesignComponent>\n  ",
+		stories: [{
+			id: "PageAreaBasic",
+			name: {
+				en: "Basic",
+				ru: "Базовые"
+			},
+			template: "\n        <DesignComponent>\n          <p>This is a basic example of PageArea content. It can contain any combination of blocks, sections, or individual UI elements.</p>\n        </DesignComponent>\n      "
+		}, {
+			id: "PageAreaSlots",
+			name: {
+				en: "Slots usage",
+				ru: "Использование слотов"
+			},
+			template: "\n        <DesignComponent>\n          <template #default>Default slot</template>\n          <template #headline>Headline slot</template>\n          <template #label>Label slot</template>\n          <template #description>Description slot</template>\n          <template #caption>Caption slot</template>\n          <template #trailing>Trailing slot</template>\n        </DesignComponent>\n      "
+		}],
+		documentation: {
+			body: "\n<StorybookDescriptions componentName={'PageArea'} type={'pageArea'}/>\n<Canvas of={Component.PageAreaBasic}/>\n\n<StorybookDescriptions componentName={'Block'} type={'differences'}/>\n    ",
+			slots: "\n<Canvas of={Component.PageAreaSlots}/>\n<StorybookDescriptions componentName={'Slot'} type={'default'}/>\n<StorybookDescriptions componentName={'Slot'} type={'headline'}/>\n<StorybookDescriptions componentName={'Slot'} type={'label'}/>\n<StorybookDescriptions componentName={'Slot'} type={'description'}/>\n<StorybookDescriptions componentName={'Slot'} type={'caption'}/>\n<StorybookDescriptions componentName={'Slot'} type={'trailing'}/>\n    "
+		},
+		ai: { description: "\nThe PageArea component serves as a foundational structural unit for application pages.\nIt helps define the main content zones and ensures consistent layout management across different views.\nTypically used as a root-level container within a specific page or sub-section to organize content blocks and handle area-specific logic.\n    " }
+	},
 	{
 		name: "Progress",
 		description: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dxtmisha/wiki",
   "private": false,
-  "version": "0.39.8",
+  "version": "0.57.0",
   "type": "module",
   "description": "Wiki documentation and storybook utilities for DXT UI design system",
   "keywords": [

package/src/media/functional/functional/composables/useApiAsyncRef/useApiAsyncRef.en.mdx

@@ -0,0 +1,43 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/functional/Composables/useApiAsyncRef - Async Initialization'/>
+
+# `useApiAsyncRef`
+
+`useApiAsyncRef` is an asynchronous wrapper over [`useApiRef`](./useApiRef.en.mdx) that performs immediate request initialization.
+
+Unlike the standard `useApiRef`, which is initialized "lazily" (on the first data access), this method calls `init()` immediately.
+
+## Key Features
+- **Immediate Initialization** — triggers the request as soon as the composable is called.
+- **Synchronous Recovery** — if the data is already in the cache, it is recovered synchronously before any asynchronous actions start.
+- **SSR Support** — utilizes `onServerPrefetch` to ensure data availability before rendering.
+
+## Parameters
+The parameters are identical to `useApiRef`.
+
+- `path?: RefOrNormal<string | undefined>` — the endpoint path.
+- `options?: ApiOptions` — request options.
+- `reactivity?: boolean` — whether to enable reactivity.
+- `conditions?: RefType<boolean>` — request conditions.
+- `transformation?: (data: T, isResponseContractValid?: ApiDataValidation) => ApiData<R>` — data transformation.
+- `validateResponseContract?: (data: T) => ApiDataValidation` — contract validation.
+- `unmounted?: boolean` — removal from cache on unmount.
+- `apiInstance?: ApiInstance` — API instance.
+
+## Return Value
+Returns the `UseApiRef<R>` object. The structure of the `UseApiRef` object is identical to the return value of [`useApiRef`](./useApiRef.en.mdx).
+
+## Example
+
+```typescript
+import { useApiAsyncRef } from '@dxtmisha/functional'
+
+// initialization triggers immediately
+const { data, loading } = useApiAsyncRef(
+  'users/list',
+  { method: 'GET' }
+)
+```
+
+

package/src/media/functional/functional/composables/useApiAsyncRef/useApiAsyncRef.ru.mdx

@@ -0,0 +1,43 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/functional/Composables/useApiAsyncRef - Асинхронная инициализация'/>
+
+# `useApiAsyncRef`
+
+`useApiAsyncRef` — это асинхронная обертка над [`useApiRef`](./useApiRef.ru.mdx), которая выполняет немедленную инициализацию запроса.
+
+В отличие от стандартного `useApiRef`, который инициализируется "лениво" (при первом обращении к данным), этот метод вызывает `init()` сразу.
+
+## Ключевые особенности
+- **Немедленная инициализация** — запускает запрос сразу при вызове хука.
+- **Синхронное восстановление** — если данные уже есть в кэше, они восстанавливаются синхронно до начала любых асинхронных действий.
+- **Поддержка SSR** — использует `onServerPrefetch` для гарантии получения данных при серверном рендеринге.
+
+## Параметры
+Параметры полностью идентичны `useApiRef`.
+
+- `path?: RefOrNormal<string | undefined>` — путь к endpoint.
+- `options?: ApiOptions` — опции запроса.
+- `reactivity?: boolean` — включить ли реактивность.
+- `conditions?: RefType<boolean>` — условия выполнения запроса.
+- `transformation?: (data: T, isResponseContractValid?: ApiDataValidation) => ApiData<R>` — преобразование данных.
+- `validateResponseContract?: (data: T) => ApiDataValidation` — валидация контракта.
+- `unmounted?: boolean` — удаление из кэша при размонтировании.
+- `apiInstance?: ApiInstance` — экземпляр API.
+
+## Возвращаемое значение
+Возвращает объект `UseApiRef<R>`. Состав объекта `UseApiRef` полностью идентичен возвращаемому значению [`useApiRef`](./useApiRef.ru.mdx).
+
+## Пример
+
+```typescript
+import { useApiAsyncRef } from '@dxtmisha/functional'
+
+// Инициализация запускается немедленно
+const { data, loading } = useApiAsyncRef(
+  'users/list',
+  { method: 'GET' }
+)
+```
+
+

package/src/media/functional/functional/composables/useApiAsyncRef/useApiAsyncRef.vi.mdx

@@ -0,0 +1,41 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/functional/Composables/useApiAsyncRef - Khởi tạo bất đồng bộ'/>
+
+# `useApiAsyncRef`
+
+`useApiAsyncRef` là một wrapper bất đồng bộ phía trên [`useApiRef`](./useApiRef.vi.mdx), thực hiện việc khởi tạo yêu cầu ngay lập tức.
+
+Khác với `useApiRef` tiêu chuẩn, vốn được khởi tạo "lười" (chỉ khi truy cập dữ liệu lần đầu), phương thức này gọi `init()` ngay lập tức.
+
+## Các tính năng chính
+- **Khởi tạo ngay lập tức** — kích hoạt yêu cầu ngay khi composable được gọi.
+- **Phục hồi đồng bộ** — nếu dữ liệu đã có trong cache, nó sẽ được phục hồi đồng bộ trước khi bắt đầu bất kỳ hành động không đồng bộ nào.
+- **Hỗ trợ SSR** — sử dụng `onServerPrefetch` để đảm bảo có dữ liệu trước khi render.
+
+## Tham số
+Các tham số hoàn toàn giống với `useApiRef`.
+
+- `path?: RefOrNormal<string | undefined>` — đường dẫn endpoint.
+- `options?: ApiOptions` — tùy chọn yêu cầu.
+- `reactivity?: boolean` — có bật tính phản ứng hay không.
+- `conditions?: RefType<boolean>` — điều kiện thực thi.
+- `transformation?: (data: T, isResponseContractValid?: ApiDataValidation) => ApiData<R>` — chuyển đổi dữ liệu.
+- `validateResponseContract?: (data: T) => ApiDataValidation` — xác thực hợp đồng dữ liệu.
+- `unmounted?: boolean` — có xóa khỏi cache khi unmount hay không.
+- `apiInstance?: ApiInstance` — instance của API.
+
+## Giá trị trả về
+Trả về đối tượng `UseApiRef<R>`. Cấu trúc của đối tượng `UseApiRef` hoàn toàn giống với giá trị trả về của [`useApiRef`](./useApiRef.vi.mdx).
+
+## Ví dụ
+
+```typescript
+import { useApiAsyncRef } from '@dxtmisha/functional'
+
+// khởi tạo kích hoạt ngay lập tức
+const { data, loading } = useApiAsyncRef(
+  'users/list',
+  { method: 'GET' }
+)
+```

package/src/media/functional/functional/composables/useApiRef/useApiRef.en.mdx

@@ -1,5 +1,3 @@
-import {Meta} from '@storybook/addon-docs/blocks'
-
 <Meta title='@dxtmisha/en/functional/Composables/useApiRef - API Requests'/>
 
 # `useApiRef`
@@ -15,7 +13,8 @@ A composable for working with API requests in Vue components. Returns reactive d
 - `options?: ApiOptions` — request options (`ApiFetch` object or method name string).
 - `reactivity?: boolean` — automatically re-run the request when `path`, `options`, or locale change. Default: `true`.
 - `conditions?: RefType<boolean>` — reactive execution condition. If `false` — the request is not made and data is cleared.
-- `transformation?: (data: T) => ApiData<R>` — response transformation function applied before saving to `data`.
+- `transformation?: (data: T, isResponseContractValid?: ApiDataValidation) => ApiData<R>` — response transformation function applied before saving to `data`. Receives the contract validation result as the second argument.
+- `validateResponseContract?: (data: T) => ApiDataValidation` — function to validate the response data contract.
 - `unmounted?: boolean` — if `true` (default), data is cleared and the watcher is stopped when the component unmounts. When `false`, `EffectScopeGlobal` is used for background persistence.
 - `apiInstance?: ApiInstance` — API instance to use for the request. Defaults to `Api.getItem()`.
 
@@ -24,6 +23,8 @@ A composable for working with API requests in Vue components. Returns reactive d
 Reactive states:
 - `data: ComputedRef<ApiData<R> | undefined>` — A reference to the loaded data (Computed). Initiates **lazy initialization** (request and watcher) on the first access.
 - `item: Ref<ApiData<R> | undefined>` — Direct reference to data (Ref). Also initiates lazy initialization upon access.
+- `isResponseContractValid: ComputedRef<boolean>` — `true` if the response contract is valid (`success` status).
+- `responseValidationResult: ComputedRef<ApiDataValidation | undefined>` — the full contract validation result object.
 - `starting: ComputedRef<boolean>` — Returns `true` if data has never been requested yet or is in the process of fetching the first portion of data (`data` is still `undefined`).
 - `loading: Ref<boolean>` — Returns `true` if any network request (initial or subsequent `reset`) is currently in progress.
 - `reading: Ref<boolean>` — A flag for an active data reading/processing process.
@@ -33,7 +34,7 @@ Methods:
 - `isLoading(): boolean` — A synchronous method that returns the current value of the `loading` flag.
 - `isReading(): boolean` — A synchronous method that returns the current value of the `reading` flag.
 - `getItem(): ApiData<R> | undefined` — Method to get the current value of `data` without creating a reactive dependency.
-- `init(): void` — Method for explicit request and watcher initialization. Triggered automatically on first access to `data`.
+- `init(awaitFetch?: boolean): Promise<void>` — Method for explicit request and watcher initialization. Triggered automatically on first access to `data`. If `awaitFetch` is `true`, it waits for the first request to complete.
 - `reset(): Promise<void>` — An asynchronous method to force re-run the request. Cancels the current active request (if any) and initiates a new one.
 - `stop(): void` — Stops watching reactive dependencies and resets `data` to `undefined`.
 - `abort(): void` — Cancels the current HTTP request via the internal `AbortController`, while keeping already loaded data in `data`.
@@ -46,6 +47,20 @@ Requests and watching mechanisms **are not started** immediately when `useApiRef
 
 `setApiRefGlobalConditions(conditions)` — sets a global condition for all `useApiRef` instances. Only works on the first call.
 
+## SSR and Initialization
+
+The `init` method is designed to manage the primary data loading process, which is critical for the correct operation of **Server Side Rendering (SSR)** and ensuring fast interface rendering on the client.
+
+### Mechanism of Operation (Hydration)
+
+1.  **Server Side (SSR):**
+    When the page is first opened, `await init()` should be called in `async setup()`. This forces the server to wait for the API response and render the component with ready-made data. The received data is automatically placed in the state cache, which is then passed to the client.
+
+2.  **Client Side (Hydration):**
+    When the browser "hydrates" the page, `useApiRef` first checks for data in the cache. If data is there (received from the server), it is immediately applied to `data`, avoiding a duplicate API request.
+
+3.  **Dynamic Navigation (Client-side Nav):**
+    If the user navigates to the page dynamically (without a page reload), the component renders immediately without waiting for `init()` to complete. This allows for instantly showing a **skeleton** or loading indicator (`loading`) while data is being fetched in the background.
 ## ApiOptions Object
 
 `ApiOptions` — can accept a string with the `method` name (e.g., `'GET'`) or an object of type `ApiFetch`. Fields of the `ApiFetch` object:
@@ -65,6 +80,7 @@ Requests and watching mechanisms **are not started** immediately when `useApiRef
 - `queryReturn?: (query: Response) => Promise<any>` — response handler instead of standard JSON reading.
 - `init?: RequestInit` — additional options for native `fetch()` (CORS, cache mode, etc.).
 - `controller?: AbortController` — controller for canceling the request.
+- `retry?: number` — number of retries on failure.
 
 ## Example
 

package/src/media/functional/functional/composables/useApiRef/useApiRef.ru.mdx

@@ -15,15 +15,18 @@ Composable для удобной работы с API-запросами во Vue
 - `options?: ApiOptions` — опции запроса (объект `ApiFetch` или строка с именем метода).
 - `reactivity?: boolean` — автоматически перезапускать запрос при изменении `path`, `options` или локали. По умолчанию: `true`.
 - `conditions?: RefType<boolean>` — реактивное условие выполнения. Если `false` — запрос не выполняется, данные сбрасываются.
-- `transformation?: (data: T) => ApiData<R>` — функция преобразования ответа перед сохранением в `data`.
+- `transformation?: (data: T, isResponseContractValid?: ApiDataValidation) => ApiData<R>` — функция преобразования ответа перед сохранением в `data`. Получает вторым аргументом результат валидации контракта.
+- `validateResponseContract?: (data: T) => ApiDataValidation` — функция для проверки контракта данных ответа.
 - `unmounted?: boolean` — если `true` (по умолчанию), данные сбрасываются и watcher останавливается при размонтировании компонента. При `false` используется `EffectScopeGlobal` для фоновой работы.
 - `apiInstance?: ApiInstance` — Экземпляр API, используемый для выполнения запроса. По умолчанию `Api.getItem()`.
 
 **Возвращает (`UseApiRef<R>`):**
 
 Реактивные состояния:
-- `data: ComputedRef<ApiData<R> | undefined>` — Ссылка на загруженные данные (Computed). Инициирует **ленивую инициализацию** (запрос и watcher) при первом обращении.
+- `data: ComputedRef<ApiData<R> | undefined>` — Ссылка на загруженные данные (Computed). Инициирует **ленивую инициализацию** (запрос и watcher) при первым обращении.
 - `item: Ref<ApiData<R> | undefined>` — Прямая ссылка на данные (Ref). Также инициирует ленивую инициализацию при доступе.
+- `isResponseContractValid: ComputedRef<boolean>` — `true`, если контракт ответа валиден (статус `success`).
+- `responseValidationResult: ComputedRef<ApiDataValidation | undefined>` — полный объект результата валидации контракта.
 - `starting: ComputedRef<boolean>` — Возвращает `true`, если данные еще ни разу не запрашивались или находятся в процессе получения первой порции данных (`data` еще `undefined`).
 - `loading: Ref<boolean>` — Возвращает `true`, если в данный момент выполняется любой сетевой запрос (первичный или последующий `reset`).
 - `reading: Ref<boolean>` — Флаг активного процесса чтения/обработки данных.
@@ -33,7 +36,7 @@ Composable для удобной работы с API-запросами во Vue
 - `isLoading(): boolean` — Синхронный метод, возвращающий текущее значение флага `loading`.
 - `isReading(): boolean` — Синхронный метод, возвращающий текущее значение флага `reading`.
 - `getItem(): ApiData<R> | undefined` — Метод для получения текущего значения `data` без создания реактивной зависимости.
-- `init(): void` — Метод для явной инициализации запроса и watchers. Вызывается автоматически при первом обращении к `data`.
+- `init(awaitFetch?: boolean): Promise<void>` — Метод для явной инициализации запроса и watchers. Вызывается автоматически при первом обращении к `data`. Если `awaitFetch` передано как `true`, дожидается выполнения первого запроса.
 - `reset(): Promise<void>` — Асинхронный метод для принудительного перезапуска запроса. Отменяет текущий активный запрос (если есть) и инициирует новый.
 - `stop(): void` — Останавливает наблюдение за реактивными зависимостями и сбрасывает `data` в `undefined`.
 - `abort(): void` — Вызывает отмену текущего HTTP-запроса через внутренний `AbortController`, сохраняя при этом уже загруженные данные в `data`.
@@ -46,6 +49,20 @@ Composable для удобной работы с API-запросами во Vue
 
 `setApiRefGlobalConditions(conditions)` — устанавливает глобальное условие для всех экземпляров `useApiRef`. Работает только один раз.
 
+## SSR и инициализация
+
+Метод `init` предназначен для управления процессом первичной загрузки данных, что критически важно для корректной работы **Server Side Rendering (SSR)** и обеспечения быстрой отрисовки интерфейса на клиенте.
+
+### Механика работы (Hydration)
+
+1.  **На стороне сервера (SSR):**
+    При первом открытии страницы необходимо вызвать `await init()` в `async setup()`. Это заставит сервер дождаться ответа от API и отрендерить компонент уже с готовыми данными. Полученные данные автоматически попадают в кэш состояния, который передается клиенту.
+
+2.  **На стороне клиента (Hydration):**
+    Когда браузер "оживляет" (гидрирует) страницу, `useApiRef` первым делом проверяет наличие данных в кэше. Если данные там есть (пришли с сервера), они мгновенно подставляются в `data`, исключая повторный запрос к API.
+
+3.  **Динамическая навигация (Client-side Nav):**
+    Если пользователь переходит на страницу динамически (без перезагрузки), компонент рендерится сразу, не дожидаясь завершения `init()`. Это позволяет мгновенно показать **скелетон (skeleton)** или индикатор загрузки (`loading`), пока данные подгружаются в фоновом режиме.
 ## Объект ApiOptions
 
 `ApiOptions` — может принимать строку с названием `method` (например, `'GET'`) или объект типа `ApiFetch`. Поля объекта `ApiFetch`:
@@ -65,6 +82,7 @@ Composable для удобной работы с API-запросами во Vue
 - `queryReturn?: (query: Response) => Promise<any>` — обработчик ответа вместо стандартного чтения JSON.
 - `init?: RequestInit` — дополнительные опции для нативного `fetch()` (CORS, режим кеша и др.).
 - `controller?: AbortController` — контроллер для отмены запроса.
+- `retry?: number` — количество повторных попыток при сбое.
 
 ## Пример
 

package/src/media/functional/functional/composables/useApiRef/useApiRef.vi.mdx

@@ -15,7 +15,8 @@ Composable để làm việc với các yêu cầu API trong Vue component. Tr
 - `options?: ApiOptions` — tùy chọn yêu cầu (đối tượng `ApiFetch` hoặc chuỗi tên phương thức).
 - `reactivity?: boolean` — tự động chạy lại yêu cầu khi `path`, `options` hoặc ngôn ngữ thay đổi. Mặc định: `true`.
 - `conditions?: RefType<boolean>` — điều kiện thực thi phản ứng. Nếu `false` — yêu cầu không được thực hiện và dữ liệu bị xóa.
-- `transformation?: (data: T) => ApiData<R>` — hàm chuyển đổi phản hồi trước khi lưu vào `data`.
+- `transformation?: (data: T, isResponseContractValid?: ApiDataValidation) => ApiData<R>` — hàm chuyển đổi phản hồi trước khi lưu vào `data`. Nhận kết quả xác thực hợp đồng ở đối số thứ hai.
+- `validateResponseContract?: (data: T) => ApiDataValidation` — hàm xác thực hợp đồng dữ liệu phản hồi.
 - `unmounted?: boolean` — nếu `true` (mặc định), dữ liệu bị xóa và watcher dừng lại khi component unmount. Khi `false`, `EffectScopeGlobal` được sử dụng để duy trì chạy nền.
 - `apiInstance?: ApiInstance` — Phiên bản API sử dụng cho yêu cầu. Mặc định là `Api.getItem()`.
 
@@ -24,6 +25,8 @@ Composable để làm việc với các yêu cầu API trong Vue component. Tr
 Trạng thái phản ứng:
 - `data: ComputedRef<ApiData<R> | undefined>` — Tham chiếu đến dữ liệu đã tải (Computed). Bắt đầu **khởi tạo lười** (yêu cầu và watcher) khi truy cập lần đầu.
 - `item: Ref<ApiData<R> | undefined>` — Tham chiếu trực tiếp đến dữ liệu (Ref). Cũng bắt đầu khởi tạo lười khi truy cập.
+- `isResponseContractValid: ComputedRef<boolean>` — `true` nếu hợp đồng phản hồi hợp lệ (trạng thái `success`).
+- `responseValidationResult: ComputedRef<ApiDataValidation | undefined>` — đối tượng kết quả xác thực hợp đồng đầy đủ.
 - `starting: ComputedRef<boolean>` — Trả về `true` nếu dữ liệu chưa bao giờ được yêu cầu hoặc đang trong quá trình lấy phần dữ liệu đầu tiên (`data` vẫn là `undefined`).
 - `loading: Ref<boolean>` — Trả về `true` nếu bất kỳ yêu cầu mạng nào (ban đầu hoặc `reset` sau đó) hiện đang được thực hiện.
 - `reading: Ref<boolean>` — Cờ cho quá trình đọc/xử lý dữ liệu đang hoạt động.
@@ -33,7 +36,7 @@ Phương thức:
 - `isLoading(): boolean` — Phương thức đồng bộ trả về giá trị hiện tại của cờ `loading`.
 - `isReading(): boolean` — Phương thức đồng bộ trả về giá trị hiện tại của cờ `reading`.
 - `getItem(): ApiData<R> | undefined` — Phương thức để lấy giá trị hiện tại của `data` mà không tạo ra phụ thuộc phản ứng.
-- `init(): void` — Phương thức để khởi tạo yêu cầu và watcher một cách rõ ràng. Tự động kích hoạt khi truy cập `data` lần đầu.
+- `init(awaitFetch?: boolean): Promise<void>` — Phương thức để khởi tạo yêu cầu và watcher một cách rõ ràng. Tự động kích hoạt khi truy cập `data` lần đầu. Nếu `awaitFetch` là `true`, nó sẽ đợi yêu cầu đầu tiên hoàn thành.
 - `reset(): Promise<void>` — Phương thức bất đồng bộ để buộc chạy lại yêu cầu. Hủy yêu cầu hiện tại (nếu có) và bắt đầu một yêu cầu mới.
 - `stop(): void` — Dừng việc theo dõi các phụ thuộc phản ứng và đặt lại `data` thành `undefined`.
 - `abort(): void` — Hủy yêu cầu HTTP hiện tại thông qua `AbortController` nội bộ, trong khi vẫn giữ lại dữ liệu đã tải trong `data`.
@@ -46,6 +49,20 @@ Yêu cầu và cơ chế theo dõi thay đổi **không được bắt đầu**
 
 `setApiRefGlobalConditions(conditions)` — thiết lập điều kiện toàn cục cho tất cả các instance `useApiRef`. Chỉ có hiệu lực một lần.
 
+## SSR và Khởi tạo
+
+Phương thức `init` được thiết kế để quản lý quá trình tải dữ liệu ban đầu, điều này cực kỳ quan trọng đối với hoạt động chính xác của **Server Side Rendering (SSR)** và đảm bảo giao diện được hiển thị nhanh chóng trên client.
+
+### Cơ chế hoạt động (Hydration)
+
+1.  **Phía Máy chủ (SSR):**
+    Khi trang được mở lần đầu tiên, hãy gọi `await init()` trong `async setup()`. Điều này buộc máy chủ phải đợi phản hồi từ API và render component với dữ liệu đã sẵn sàng. Dữ liệu nhận được sẽ tự động được đưa vào bộ nhớ đệm trạng thái (cache), sau đó được chuyển đến client.
+
+2.  **Phía Máy khách (Hydration):**
+    Khi trình duyệt "kích hoạt" (hydrate) trang, `useApiRef` trước tiên sẽ kiểm tra dữ liệu trong bộ nhớ đệm. Nếu dữ liệu có ở đó (được nhận từ máy chủ), chúng sẽ được áp dụng ngay lập tức vào `data`, tránh việc lặp lại yêu cầu API.
+
+3.  **Điều hướng Động (Client-side Nav):**
+    Nếu người dùng điều hướng đến trang một cách linh hoạt (không tải lại trang), component sẽ render ngay lập tức mà không cần đợi `init()` hoàn thành. Điều này cho phép hiển thị ngay lập tức **skeleton** hoặc chỉ báo đang tải (`loading`) trong khi dữ liệu đang được tải ở chế độ nền.
 ## Đối tượng ApiOptions
 
 `ApiOptions` — có thể nhận một chuỗi tên `method` (ví dụ: `'GET'`) hoặc một đối tượng kiểu `ApiFetch`. Các trường của đối tượng `ApiFetch`:
@@ -65,6 +82,7 @@ Yêu cầu và cơ chế theo dõi thay đổi **không được bắt đầu**
 - `queryReturn?: (query: Response) => Promise<any>` — trình xử lý phản hồi thay vì đọc JSON tiêu chuẩn.
 - `init?: RequestInit` — các tùy chọn bổ sung cho `fetch()` gốc (CORS, chế độ cache, v.v.).
 - `controller?: AbortController` — bộ điều khiển để hủy yêu cầu.
+- `retry?: number` — số lần thử lại khi thất bại.
 
 ## Ví dụ
 

package/src/media/functional/functional/functions/computedAsync/computedAsync.en.mdx

@@ -8,6 +8,7 @@ Creates a computed property that can handle asynchronous getters. Unlike Vue's s
 
 **Parameters:**
 - `getter: (() => Promise<R>) | (() => R) | R` — An async function, synchronous function, or raw value to compute the result from.
+- `initialState?: R` — The initial value of the result.
 - `ignore?: R` — A value to be ignored (will not be set as the result).
 - `debugOptions?: DebuggerOptions` — Options used for debugging reactive computations, supported by Vue.js.
 
@@ -17,6 +18,13 @@ Creates a computed property that can handle asynchronous getters. Unlike Vue's s
 ```typescript
 import { computedAsync } from '@dxtmisha/functional'
 
+// Initial state
+const status = computedAsync(async () => {
+  await new Promise(resolve => setTimeout(resolve, 1000))
+  return 'online'
+}, 'offline')
+// status.value is 'offline' immediately, and 'online' after 1 second
+
 // Async getter
 const data = computedAsync(async () => {
   const response = await fetch('/api/data')

package/src/media/functional/functional/functions/computedAsync/computedAsync.ru.mdx

@@ -8,6 +8,7 @@ import { Meta } from '@storybook/addon-docs/blocks'
 
 **Параметры:**
 - `getter: (() => Promise<R>) | (() => R) | R` — Асинхронная функция, синхронная функция или прямое значение для вычисления результата.
+- `initialState?: R` — Начальное значение результата.
 - `ignore?: R` — Значение, которое должно быть проигнорировано (не будет установлено в результат).
 - `debugOptions?: DebuggerOptions` — Опции отладки реактивных вычислений Vue.js.
 
@@ -17,6 +18,13 @@ import { Meta } from '@storybook/addon-docs/blocks'
 ```typescript
 import { computedAsync } from '@dxtmisha/functional'
 
+// Начальное значение
+const status = computedAsync(async () => {
+  await new Promise(resolve => setTimeout(resolve, 1000))
+  return 'online'
+}, 'offline')
+// status.value будет 'offline' сразу, и 'online' через 1 секунду
+
 // Асинхронный геттер
 const data = computedAsync(async () => {
   const response = await fetch('/api/data')

package/src/media/functional/functional/functions/computedAsync/computedAsync.vi.mdx

@@ -8,6 +8,7 @@ Tạo một thuộc tính computed có thể xử lý các getter bất đồng
 
 **Tham số:**
 - `getter: (() => Promise<R>) | (() => R) | R` — Hàm bất đồng bộ, hàm đồng bộ, hoặc giá trị trực tiếp dùng để tính toán kết quả.
+- `initialState?: R` — Giá trị ban đầu của kết quả.
 - `ignore?: R` — Giá trị cần bỏ qua (sẽ không được thiết lập vào kết quả).
 - `debugOptions?: DebuggerOptions` — Tùy chọn dùng để gỡ lỗi các phép tính phản ứng, được hỗ trợ bởi Vue.js.
 
@@ -17,6 +18,13 @@ Tạo một thuộc tính computed có thể xử lý các getter bất đồng
 ```typescript
 import { computedAsync } from '@dxtmisha/functional'
 
+// Trạng thái ban đầu
+const status = computedAsync(async () => {
+  await new Promise(resolve => setTimeout(resolve, 1000))
+  return 'online'
+}, 'offline')
+// status.value là 'offline' ngay lập tức, và 'online' sau 1 giây
+
 // Getter bất đồng bộ
 const data = computedAsync(async () => {
   const response = await fetch('/api/data')

package/src/media/functional/functional/functions/computedEternity/computedEternity.en.mdx

@@ -8,6 +8,7 @@ Creates a computed property that is computed on demand and cached. The value is
 
 **Parameters:**
 - `getter: () => Promise<T> | T` — A function that returns the value to be computed (can be synchronous or asynchronous).
+- `initialState?: T` — The initial value of the result.
 
 **Returns:**
 `CustomRef<T>` — A reactive custom ref containing the resolved result of the getter.
@@ -15,6 +16,13 @@ Creates a computed property that is computed on demand and cached. The value is
 ```typescript
 import { computedEternity } from '@dxtmisha/functional'
 
+// Initial state
+const status = computedEternity(async () => {
+  await new Promise(resolve => setTimeout(resolve, 1000))
+  return 'online'
+}, 'offline')
+// Status.value is 'offline' until the getter resolves
+
 // Async getter - will only be called when 'data.value' is first accessed
 const data = computedEternity(async () => {
   const response = await fetch('/api/data')