@dxtmisha/wiki 0.24.2 → 0.25.1

package/src/media/mdx/FieldMessage/wikiMdxFieldMessage.ts

@@ -2,10 +2,8 @@ import type { StorybookComponentsMdxItem } from '../../../types/storybookTypes'
 
 import fieldMessageEn from './fieldMessage.en.mdx'
 import fieldMessageRu from './fieldMessage.ru.mdx'
-import slotHelperEn from './slot.helper.en.mdx'
-import slotHelperRu from './slot.helper.ru.mdx'
-import slotValidationEn from './slot.validation.en.mdx'
-import slotValidationRu from './slot.validation.ru.mdx'
+import slotsEn from './slots.en.mdx'
+import slotsRu from './slots.ru.mdx'
 
 /**
  * MDX files for FieldMessage component
@@ -15,17 +13,13 @@ import slotValidationRu from './slot.validation.ru.mdx'
 export const wikiMdxFieldMessage: StorybookComponentsMdxItem = {
   name: 'FieldMessage',
   descriptions: {
-    'fieldMessage': {
+    fieldMessage: {
       en: fieldMessageEn,
       ru: fieldMessageRu
     },
-    'slot.helper': {
-      en: slotHelperEn,
-      ru: slotHelperRu
-    },
-    'slot.validation': {
-      en: slotValidationEn,
-      ru: slotValidationRu
+    slots: {
+      en: slotsEn,
+      ru: slotsRu
     }
   }
 }

package/src/media/mdx/Icon/expose.isActive.en.mdx

@@ -1,13 +1,5 @@
 ### `isActive`
 
-Computed property that determines whether the additional icon is active.
+Computed state indicating whether the alternative representation is active (when both `active` and `iconActive` are set).
 
-```ts
-readonly isActive: ComputedRef<boolean>
-```
-
-Returns `true` only when both conditions are met:
-- The `active` property is set to `true`
-- The `iconActive` property is defined (not empty)
-
-This property is used internally by the component to control the display of primary and additional icons.
+**Type:** `ComputedRef<boolean>`

package/src/media/mdx/Icon/expose.isActive.ru.mdx

@@ -1,13 +1,5 @@
 ### `isActive`
 
-Вычисляемое свойство, которое определяет, активна ли дополнительная иконка.
+Вычисляемое состояние, указывающее активно ли альтернативное представление (когда одновременно установлены `active` и `iconActive`).
 
-```ts
-readonly isActive: ComputedRef<boolean>
-```
-
-Возвращает `true` только когда выполняются оба условия:
-- Свойство `active` установлено в `true`
-- Свойство `iconActive` задано (не пустое)
-
-Это свойство используется внутри компонента для управления отображением основной и дополнительной иконок.
+**Тип:** `ComputedRef<boolean>`

package/src/media/mdx/Icon/icon.en.mdx

@@ -1,6 +1,24 @@
 ## Icon State Management
 
-The `icon`, `iconActive`, and `active` properties control the display of the icon based on its state. This allows for the creation of dynamic and interactive elements.
+A component for displaying icons with support for active state, rotation, loading, and skeleton integration.
+
+Icon provides a unified interface for working with icons in the design system, supporting both the main icon and an alternative for the active state. The component automatically manages switching between icons, handles loading events, and integrates with the skeleton system to display loading states.
+
+**Key Features:**
+
+- Display of main and active icons with smooth transitions
+- Icon rotation at a specified angle
+- Disabled and hide states for visibility control
+- Image loading events for icons
+- Integration with Skeleton for loading states
+- Support within other components (Button, Cell, Chip, Field)
+
+**Typical Use Cases:**
+
+- Icons in buttons and navigation elements
+- Interactive icons with state changes
+- State indicators in forms and lists
+- Decorative interface elements with animation
 
 ### Properties
 
@@ -23,21 +41,37 @@ The `icon`, `iconActive`, and `active` properties control the display of the ico
 ### Usage Example
 
 ```html
-<!-- Normal icon -->
-<Icon icon="home" />
+<script setup>
+import { ref } from 'vue'
+import { D1Icon } from '@dxtmisha/d1'
 
-<!-- Active icon -->
-<!-- `favorite` will be displayed because active=true -->
-<Icon icon="favorite_border" iconActive="favorite" :active="true" />
+const isActive = ref(false)
+</script>
 
-<!-- Dynamic state toggle -->
 <template>
-  <Icon
+  <!-- Normal icon -->
+  <D1Icon icon="home" />
+
+  <!-- Active icon -->
+  <!-- `favorite` will be displayed because active=true -->
+  <D1Icon icon="favorite_border" icon-active="favorite" :active="true" />
+
+  <!-- Dynamic state toggle -->
+  <D1Icon
     icon="visibility"
-    iconActive="visibility_off"
+    icon-active="visibility_off"
     :active="isVisible"
     @click="isVisible = !isVisible"
   />
+
+  <D1Icon
+    icon="home"
+    icon-active="favorite"
+    :active="isActive"
+    turn="90"
+    @load="onIconLoad"
+  />
 </template>
 ```
 
+> The Icon component can be used both standalone and as part of other UI components through the `icon`, `icon-trailing`, and `icon-active` properties.

package/src/media/mdx/Icon/icon.ru.mdx

@@ -1,43 +1,42 @@
-## Управление состоянием иконки
+## Icon
 
-Свойства `icon`, `iconActive` и `active` отвечают за управление отображением иконки в зависимости от её состояния. Это позволяет создавать динамичные и интерактивные элементы.
+Компонент для отображения иконок с поддержкой активного состояния, поворота, загрузки и интеграции со скелетоном.
 
-### Свойства
+Icon предоставляет унифицированный интерфейс для работы с иконками в дизайн-системе, поддерживая как основную иконку, так и альтернативную для активного состояния. Компонент автоматически управляет переключением между иконками, обрабатывает события загрузки и интегрируется с системой скелетонов для отображения состояния загрузки.
 
-- **`icon`** — Основная иконка, отображаемая по умолчанию.
-- **`iconActive`** — Иконка, которая отображается, когда компонент находится в активном состоянии (`active` = `true`).
-- **`active`** — Булево свойство, которое переключает состояние компонента между обычным и активным.
+**Основные возможности:**
 
-### Описание
+- Отображение основной и активной иконки с плавным переключением
+- Поворот иконки на заданный угол
+- Состояния disabled и hide для управления видимостью
+- События загрузки изображений иконок
+- Интеграция со Skeleton для состояний загрузки
+- Поддержка в составе других компонентов (Button, Cell, Chip, Field)
 
-- Свойство `icon` является основным и обязательным для отображения иконки.
-- Если `iconActive` не задано, то при изменении состояния `active` визуально ничего не изменится.
-- Когда `active` установлено в `true`, компонент будет пытаться отобразить иконку, указанную в `iconActive`.
-- Свойство `active` можно использовать для создания переключателей, индикаторов и других интерактивных элементов.
+**Типичные сценарии использования:**
 
-### Рекомендации
-
-- Используйте `iconActive` для обеспечения визуальной обратной связи при взаимодействии с пользователем (например, при нажатии или выборе).
-- Убедитесь, что `icon` и `iconActive` достаточно различны визуально, чтобы пользователь мог легко определить изменение состояния.
-
-### Пример использования
+- Иконки в кнопках и навигационных элементах
+- Интерактивные иконки с изменением состояния
+- Индикаторы состояния в формах и списках
+- Декоративные элементы интерфейса с анимацией
 
 ```html
-<!-- Обычная иконка -->
-<Icon icon="home" />
+<script setup>
+import { ref } from 'vue'
+import { D1Icon } from '@dxtmisha/d1'
 
-<!-- Активная иконка -->
-<!-- Отобразится `favorite`, так как active=true -->
-<Icon icon="favorite_border" iconActive="favorite" :active="true" />
+const isActive = ref(false)
+</script>
 
-<!-- Динамическое переключение состояния -->
 <template>
-  <Icon
-    icon="visibility"
-    iconActive="visibility_off"
-    :active="isVisible"
-    @click="isVisible = !isVisible"
+  <D1Icon
+    icon="home"
+    icon-active="favorite"
+    :active="isActive"
+    turn="90"
+    @load="onIconLoad"
   />
 </template>
 ```
 
+> Компонент Icon может использоваться как самостоятельно, так и в составе других UI-компонентов через свойства `icon`, `icon-trailing` и `icon-active`.

package/src/media/mdx/Image/adaptive.en.mdx

@@ -1,32 +1,75 @@
-## Adaptive scaling and related properties
+## Adaptive scaling
 
-### Description
+The `adaptive`, `adaptiveGroup`, `adaptiveAlways`, `objectWidth`, and `objectHeight` properties control automatic image scaling to ensure visual consistency of physical object sizes across different images.
 
-The `adaptive` property enables automatic scaling and alignment of images. For correct operation, it is recommended to use it together with additional properties that allow you to precisely control the behavior and display of the image.
+**Properties:**
 
-### Properties
+- `adaptive` — enables adaptive scaling mode
+- `adaptiveGroup` — group name for scale synchronization (default `'basic'`)
+- `objectWidth` — physical width of the object in the image in millimeters
+- `objectHeight` — physical height of the object in the image in millimeters
+- `adaptiveAlways` — perform calculations even for invisible elements
 
-- **adaptive** — Enables adaptive scaling mode for the image relative to other elements with the same `adaptive-group`.
-- **object-width** — The physical width of the object in the image (in millimeters, pixels, or other units). Used for scale calculation.
-- **object-height** — The physical height of the object in the image. Can be used instead of or together with `object-width`.
-- **adaptive-group** — Adaptivity group. Elements with the same value of this property will be scaled proportionally to each other.
-- **adaptive-always** — If specified, scaling and calculations will always be performed, even if the element is hidden off-screen.
+Properties work together to ensure proportional display of images with objects of different physical sizes. When `adaptive` is activated, the component starts tracking element dimensions and comparing them with other images in the same group, automatically selecting the optimal scale for each element.
 
-### Recommendations
+The `objectWidth` or `objectHeight` properties specify the real physical dimensions of the object in the image in millimeters. These values are necessary for calculating the scaling coefficient — the component uses them to determine how much to enlarge or reduce the image so that objects in different images appear the same size. It is sufficient to specify only one property — either width or height.
 
-- Always specify at least one of the parameters: `object-width` or `object-height` for correct adaptivity.
-- Use `adaptive-group` if you need to synchronize the scale of several images.
-- Use `adaptive-always` only when necessary to avoid unnecessary calculations.
+The component automatically determines which axis (horizontal or vertical) to scale on, based on available dimensions and image proportions. If `objectWidth` is specified, scaling will occur horizontally, if `objectHeight` — vertically. This allows flexible work with images of different orientations.
 
-### Usage example
+Elements with the same `adaptiveGroup` value scale synchronously, ensuring consistent visual object sizes across all images in the group. This is especially useful when displaying product galleries or comparison tables where maintaining visual size correspondence is important.
+
+For performance optimization, scaling calculations are performed only for visible elements within the viewport plus a small margin. If an element is outside the visible area, calculations are paused until the element appears on screen. The `adaptiveAlways` property disables this optimization and forces the component to constantly recalculate the scale regardless of element visibility.
 
 ```html
-<!-- Adaptive image with specified object width -->
-<Image adaptive object-width="63.5" />
+<script setup>
+import { ref } from 'vue'
+
+const phone1 = ref('/images/phone-model-a.png')
+const phone2 = ref('/images/phone-model-b.png')
+const phone3 = ref('/images/phone-model-c.png')
+</script>
+
+<template>
+  <!-- Basic usage with object width -->
+  <Image
+    :value="phone1"
+    adaptive
+    object-width="76.2"
+  />
+
+  <!-- Multiple images in one group -->
+  <Image
+    :value="phone1"
+    adaptive
+    adaptive-group="phones"
+    object-width="76.2"
+  />
+  <Image
+    :value="phone2"
+    adaptive
+    adaptive-group="phones"
+    object-width="71.9"
+  />
+  <Image
+    :value="phone3"
+    adaptive
+    adaptive-group="phones"
+    object-width="129.9"
+  />
 
-<!-- Adaptive image with height and group -->
-<Image adaptive object-height="40" adaptive-group="products" />
+  <!-- With height instead of width -->
+  <Image
+    adaptive
+    object-height="154.8"
+    :value="phone1"
+  />
 
-<!-- Constant scaling regardless of visibility -->
-<Image adaptive object-width="50" adaptive-always />
+  <!-- Constant scaling -->
+  <Image
+    adaptive
+    adaptive-always
+    object-width="76.2"
+    :value="phone1"
+  />
+</template>
 ```

package/src/media/mdx/Image/adaptive.ru.mdx

@@ -1,38 +1,75 @@
-## Адаптивное масштабирование и связанные параметры
+## Адаптивное масштабирование
 
-Свойство `adaptive` включает режим автоматического масштабирования и выравнивания изображений. Для корректной работы рекомендуется использовать его совместно с дополнительными свойствами, которые позволяют точно управлять поведением и отображением изображения.
+Свойства `adaptive`, `adaptiveGroup`, `adaptiveAlways`, `objectWidth` и `objectHeight` управляют автоматическим масштабированием изображений для обеспечения визуального соответствия физических размеров объектов на разных изображениях.
 
-### Свойства
+**Свойства:**
 
-- **adaptive** — Включает режим адаптивного масштабирования изображения относительно других элементов с тем же `adaptive-group`.
-- **object-width** — Физическая ширина объекта на изображении (в миллиметрах, пикселях или другой единице). Используется для расчёта масштаба.
-- **object-height** — Физическая высота объекта на изображении. Может использоваться вместо или вместе с `object-width`.
-- **adaptive-group** — Группа адаптивности. Элементы с одинаковым значением этого свойства будут масштабироваться пропорционально друг другу.
-- **adaptive-always** — Если указано, масштабирование и расчёты будут выполняться всегда, даже если элемент скрыт за пределами экрана.
+- `adaptive` — включает режим адаптивного масштабирования
+- `adaptiveGroup` — название группы для синхронизации масштаба (по умолчанию `'basic'`)
+- `objectWidth` — физическая ширина объекта на изображении в миллиметрах
+- `objectHeight` — физическая высота объекта на изображении в миллиметрах
+- `adaptiveAlways` — выполнять расчёты даже для невидимых элементов
 
-### Описание
+Свойства работают совместно для обеспечения пропорционального отображения изображений с объектами разных физических размеров. При активации `adaptive` компонент начинает отслеживать размеры элемента и сравнивать их с другими изображениями в той же группе, автоматически подбирая оптимальный масштаб для каждого элемента.
 
-- Свойство `adaptive` позволяет автоматически подбирать масштаб изображения, чтобы оно выглядело пропорционально с другими элементами в той же группе.
-- `object-width` и `object-height` задают реальные размеры объекта на изображении, что необходимо для корректного расчёта масштаба.
-- `adaptive-group` объединяет элементы в одну группу для совместного масштабирования.
-- `adaptive-always` обеспечивает постоянные вычисления масштаба, даже если элемент временно скрыт.
-- Все свойства могут использоваться совместно для достижения нужного эффекта.
+Свойства `objectWidth` или `objectHeight` задают реальные физические размеры объекта на изображении в миллиметрах. Эти значения необходимы для расчёта коэффициента масштабирования — компонент использует их для определения, во сколько раз нужно увеличить или уменьшить изображение, чтобы объекты на разных изображениях выглядели одинакового размера. Достаточно указать только одно из свойств — либо ширину, либо высоту.
 
-### Рекомендации
+Компонент автоматически определяет, по какой оси (горизонтальной или вертикальной) производить масштабирование, основываясь на доступных размерах и пропорциях изображения. Если указан `objectWidth`, масштабирование будет происходить по горизонтали, если `objectHeight` — по вертикали. Это позволяет гибко работать с изображениями разных ориентаций.
 
-- Всегда указывайте хотя бы один из параметров: `object-width` или `object-height` для корректной работы адаптивности.
-- Используйте `adaptive-group`, если требуется синхронизировать масштаб нескольких изображений.
-- Применяйте `adaptive-always` только при необходимости, чтобы избежать лишних вычислений.
+Элементы с одинаковым значением `adaptiveGroup` масштабируются синхронно, обеспечивая одинаковый визуальный размер объектов на всех изображениях группы. Это особенно полезно при отображении галерей продуктов или сравнительных таблиц, где важно сохранить визуальное соответствие размеров.
 
-### Пример использования
+Для оптимизации производительности расчёты масштабирования выполняются только для видимых элементов в пределах области просмотра (viewport) плюс небольшой запас. Если элемент находится за пределами видимой области, расчёты приостанавливаются до момента, когда элемент появится на экране. Свойство `adaptiveAlways` отключает эту оптимизацию и заставляет компонент постоянно пересчитывать масштаб независимо от видимости элемента.
 
 ```html
-<!-- Адаптивное изображение с указанием ширины объекта -->
-<Image adaptive object-width="63.5" />
+<script setup>
+import { ref } from 'vue'
 
-<!-- Адаптивное изображение с высотой и группой -->
-<Image adaptive object-height="40" adaptive-group="products" />
+const phone1 = ref('/images/phone-model-a.png')
+const phone2 = ref('/images/phone-model-b.png')
+const phone3 = ref('/images/phone-model-c.png')
+</script>
 
-<!-- Постоянное масштабирование вне зависимости от видимости -->
-<Image adaptive object-width="50" adaptive-always />
+<template>
+  <!-- Базовое использование с шириной объекта -->
+  <Image
+    :value="phone1"
+    adaptive
+    object-width="76.2"
+  />
+
+  <!-- Несколько изображений в одной группе -->
+  <Image
+    :value="phone1"
+    adaptive
+    adaptive-group="phones"
+    object-width="76.2"
+  />
+  <Image
+    :value="phone2"
+    adaptive
+    adaptive-group="phones"
+    object-width="71.9"
+  />
+  <Image
+    :value="phone3"
+    adaptive
+    adaptive-group="phones"
+    object-width="129.9"
+  />
+
+  <!-- С высотой вместо ширины -->
+  <Image
+    adaptive
+    object-height="154.8"
+    :value="phone1"
+  />
+
+  <!-- Постоянное масштабирование -->
+  <Image
+    adaptive
+    adaptive-always
+    object-width="76.2"
+    :value="phone1"
+  />
+</template>
 ```

package/src/media/mdx/Image/event.load.en.mdx

@@ -1,4 +1,39 @@
 ### `load`
 
-Triggered after the image is loaded.
-The handler receives an object `ImageEventData` with image data and source type.
+Event fires after the image is loaded.
+
+**Parameters:**
+- `image: ImageEventData` — object with image data
+
+**ImageEventData structure:**
+- `type: ImageTypeItem` — image type (`'image'`, `'icon'`, `'pdf'`, `'file'`, `'flag'`, `'color'`, etc.)
+- `image: ImageEventItem` — image data (`ImageItem` object, URL string, or `undefined`)
+
+**ImageItem structure (when image is an object):**
+- `width: number` — image width
+- `height: number` — image height
+- `image: HTMLImageElement` — image DOM element
+- `src: string` — image source (URL)
+
+```html
+<script setup>
+const handleLoad = (data) => {
+  console.log('Image type:', data.type)
+
+  if (typeof data.image === 'object' && data.image) {
+    console.log('Width:', data.image.width)
+    console.log('Height:', data.image.height)
+    console.log('URL:', data.image.src)
+  } else {
+    console.log('Image URL:', data.image)
+  }
+}
+</script>
+
+<template>
+  <Image
+    src="/path/to/image.jpg"
+    @load="handleLoad"
+  />
+</template>
+```

package/src/media/mdx/Image/event.load.ru.mdx

@@ -1,12 +1,39 @@
 ### `load`
 
-Событие, которое срабатывает после загрузки изображения.
+Событие срабатывает после загрузки изображения.
 
-```ts
-function onLoad (image: ImageEventData) {
-  // обработка загруженного изображения
+**Параметры:**
+- `image: ImageEventData` — объект с данными изображения
+
+**Структура ImageEventData:**
+- `type: ImageTypeItem` — тип изображения (`'image'`, `'icon'`, `'pdf'`, `'file'`, `'flag'`, `'color'` и др.)
+- `image: ImageEventItem` — данные изображения (объект `ImageItem`, строка URL или `undefined`)
+
+**Структура ImageItem (если image - объект):**
+- `width: number` — ширина изображения
+- `height: number` — высота изображения
+- `image: HTMLImageElement` — DOM элемент изображения
+- `src: string` — источник изображения (URL)
+
+```html
+<script setup>
+const handleLoad = (data) => {
+  console.log('Тип изображения:', data.type)
+
+  if (typeof data.image === 'object' && data.image) {
+    console.log('Ширина:', data.image.width)
+    console.log('Высота:', data.image.height)
+    console.log('URL:', data.image.src)
+  } else {
+    console.log('URL изображения:', data.image)
+  }
 }
-```
+</script>
 
-Параметры:
-- `image` — `ImageEventData` — данные изображения и тип источника
+<template>
+  <Image
+    src="/path/to/image.jpg"
+    @load="handleLoad"
+  />
+</template>
+```

package/src/media/mdx/Image/{expose.type.ru.mdx → expose.en.mdx}

@@ -1,6 +1,10 @@
 ### `type`
 
-Тип загруженного изображения.
+Type of the loaded image.
+
+**Type:** `ComputedRef<ImageTypeItem>`
+
+**Possible values:**
 
 ```ts
 enum ImageTypeValue {
@@ -19,3 +23,9 @@ enum ImageTypeValue {
   icon = 'icon'
 }
 ```
+
+### `data`
+
+Information about the loaded image, including its dimensions and source.
+
+**Type:** `Ref<ImageEventItem>`

package/src/media/mdx/Image/expose.ru.mdx

@@ -0,0 +1,31 @@
+### `type`
+
+Тип загруженного изображения.
+
+**Тип:** `ComputedRef<ImageTypeItem>`
+
+**Возможные значения:**
+
+```ts
+enum ImageTypeValue {
+  pdf = 'pdf',
+  file = 'file',
+  image = 'image',
+  flag = 'flag',
+  color = 'color',
+  public = 'public',
+  filled = 'filled',
+  outlined = 'outlined',
+  round = 'round',
+  sharp = 'sharp',
+  twoTone = 'two-tone',
+  material = 'material',
+  icon = 'icon'
+}
+```
+
+### `data`
+
+Информация о загруженном изображении, включая его размеры и источник.
+
+**Тип:** `Ref<ImageEventItem>`

package/src/media/mdx/Image/image.en.mdx

@@ -0,0 +1,46 @@
+Universal component for displaying images, icons, and PDF documents with advanced size, positioning, and adaptivity control.
+
+Image provides flexible API for working with various types of visual content: from simple icons to complex images with cropping and adaptive scaling. The component automatically detects the source type, supports coordinate positioning, adaptive resizing, and various fill modes.
+
+**Key Features:**
+
+- Support for multiple source types (icons, URLs, Files, PDFs)
+- Adaptive scaling with aspect ratio preservation
+- Coordinate-based cropping and precise positioning
+- Fill modes: auto, contain, cover
+- Automatic content type detection
+- CSS variable integration for flexible styling
+- Load events with complete type and data information
+
+**Typical Use Cases:**
+
+- Displaying user avatars and uploaded images
+- Working with interface icons
+- PDF document previews
+- Adaptive image galleries
+- Background images with cropping
+
+```html
+<script setup>
+import { ref } from 'vue'
+import { Image } from '@dxtmisha/constructor'
+
+const imageUrl = ref('https://example.com/image.jpg')
+
+function handleLoad(data) {
+  console.log('Image loaded:', data.type, data.image)
+}
+</script>
+
+<template>
+  <Image
+    :value="imageUrl"
+    size="cover"
+    adaptive
+    :coordinator="[0, 0, 100, 100]"
+    @load="handleLoad"
+  />
+</template>
+```
+
+> The component automatically manages content type and optimizes display based on the source.