@dxtmisha/wiki 0.24.1 → 0.24.3

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.

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

@@ -0,0 +1,47 @@
+Универсальный компонент для отображения изображений, иконок и PDF-документов с расширенными возможностями управления размером, позиционированием и адаптивностью.
+
+Image предоставляет гибкий API для работы с различными типами визуального контента: от простых иконок до сложных изображений с кадрированием и адаптивным масштабированием. Компонент автоматически определяет тип источника, поддерживает координатное позиционирование, адаптивное изменение размеров и различные режимы заполнения.
+
+**Основные возможности:**
+
+- Поддержка множества типов источников (иконки, URL, File, PDF)
+- Адаптивное масштабирование с сохранением пропорций
+- Координатное кадрирование и точное позиционирование
+- Режимы заполнения: auto, contain, cover
+- Автоматическое определение типа контента
+- Работа с CSS-переменными для гибкой стилизации
+- События загрузки с полной информацией о типе и данных
+
+**Типичные сценарии использования:**
+
+- Отображение пользовательских аватаров и загруженных изображений
+- Работа с иконками в интерфейсе
+- Превью PDF-документов
+- Адаптивные галереи изображений
+- Фоновые изображения с кадрированием
+
+```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>
+```
+
+> Компонент автоматически управляет типом контента и оптимизирует отображение в зависимости от источника.
+

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

@@ -1,32 +1,32 @@
 ## Image display control
 
-### Description
+The `size`, `coordinator`, `x`, and `y` properties allow you to precisely control image scaling, visible area, and positioning within the container.
 
-The `size`, `coordinator`, `x`, and `y` properties allow you to precisely control image scaling, visible area, and positioning within the container. Each parameter is responsible for its own aspect of display and can be used individually or together to achieve the desired visual effect.
+**Properties:**
 
-### Properties
+- `size` — scaling and fill mode of the image (`auto`, `contain`, `cover`)
+- `coordinator` — array of coordinates for cropping the display area `[left, top, right, bottom]` in percentages
+- `x` — horizontal offset of the image (pixels, percentages)
+- `y` — vertical offset of the image (pixels, percentages)
 
-- **size** — Defines the scaling and fill mode of the image inside the container. Possible values: `auto` (default), `contain` (fit completely), `cover` (fill the container, possibly cropping the image).
-- **coordinator** — An array of four values that defines the visible area of the image: cropping from the left, top, right, and bottom, specified as percentages relative to the original image. Format: `[left, top, right, bottom]`.
-- **x** — Horizontal offset (X axis) of the image relative to the container or selected area. Can be set in pixels, percentages, or other supported units.
-- **y** — Vertical offset (Y axis) of the image relative to the container or selected area. Can be set in pixels, percentages, or other supported units.
-
-### Recommendations
-
-- Use `size` to select the appropriate image display mode for your layout and task.
-- The `coordinator` property is convenient for cropping or highlighting the desired part of the image.
-- Use the `x` and `y` parameters for precise image positioning within the container.
-- Combine parameters to achieve complex display effects.
-
-### Usage example
+Properties work together or individually. The `size` value defines the scaling mode: `auto` uses the original size, `contain` fits the image completely, `cover` fills the container with possible cropping. The `coordinator` property sets the visible area by cropping the image at specified coordinates. The `x` and `y` parameters shift the image relative to the container for precise positioning.
 
 ```html
-<!-- Image with content mode -->
+<!-- Scaling mode -->
 <Image value="image.png" size="contain" />
 
-<!-- Cropping the image by coordinates -->
+<!-- Cropping by coordinates -->
 <Image value="image.png" :coordinator="[10, 20, 100, 80]" />
 
-<!-- Shifting the image by X and Y -->
+<!-- Position offset -->
 <Image value="image.png" x="15" y="-10" />
+
+<!-- Combined parameters -->
+<Image
+  value="image.png"
+  size="cover"
+  :coordinator="[0, 0, 100, 50]"
+  x="10"
+  y="5"
+/>
 ```

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

@@ -1,36 +1,32 @@
 ## Управление отображением изображения
 
-### Описание
+Свойства `size`, `coordinator`, `x` и `y` позволяют детально управлять масштабированием, областью видимости и позиционированием изображения внутри контейнера.
 
-Свойства `size`, `coordinator`, `x` и `y` позволяют детально управлять масштабированием,
-областью видимости и позиционированием изображения внутри контейнера.
-Каждый параметр отвечает за свой аспект отображения и может использоваться как по отдельности,
-так и совместно для достижения нужного визуального эффекта.
+**Свойства:**
 
-### Свойства
+- `size` — режим масштабирования и заполнения изображения (`auto`, `contain`, `cover`)
+- `coordinator` — массив координат для обрезки области отображения `[left, top, right, bottom]` в процентах
+- `x` — смещение изображения по горизонтали (пиксели, проценты)
+- `y` — смещение изображения по вертикали (пиксели, проценты)
 
-- **size** — Определяет режим масштабирования и заполнения изображения внутри контейнера.
-Возможные значения: `auto` (по умолчанию), `contain` (вписать полностью), `cover` (заполнить контейнер с возможной обрезкой).
-- **coordinator** — Массив из четырёх значений, определяющий область изображения для отображения: обрезка слева, сверху, справа и снизу, задаётся в процентах относительно исходного изображения. Формат: `[left, top, right, bottom]`.
-- **x** — Смещение изображения по горизонтали (ось X) относительно контейнера или выбранной области. Может быть задано в пикселях, процентах или других поддерживаемых единицах.
-- **y** — Смещение изображения по вертикали (ось Y) относительно контейнера или выбранной области. Может быть задано в пикселях, процентах или других поддерживаемых единицах.
-
-### Рекомендации
-
-- Используйте `size` для выбора подходящего режима отображения изображения в зависимости от задачи и макета.
-- Свойство `coordinator` удобно для реализации обрезки или выделения нужной части изображения.
-- Параметры `x` и `y` применяйте для точного позиционирования изображения внутри контейнера.
-- Комбинируйте параметры для достижения сложных эффектов отображения.
-
-### Пример использования
+Свойства работают совместно или по отдельности. Значение `size` определяет режим масштабирования: `auto` использует исходный размер, `contain` вписывает изображение полностью, `cover` заполняет контейнер с возможной обрезкой. Свойство `coordinator` задаёт видимую область, обрезая изображение по указанным координатам. Параметры `x` и `y` смещают изображение относительно контейнера для точного позиционирования.
 
 ```html
-<!-- Изображение с режимом contain -->
+<!-- Режим масштабирования -->
 <Image value="image.png" size="contain" />
 
-<!-- Обрезка изображения по координатам -->
+<!-- Обрезка по координатам -->
 <Image value="image.png" :coordinator="[10, 20, 100, 80]" />
 
-<!-- Смещение изображения по X и Y -->
+<!-- Смещение позиции -->
 <Image value="image.png" x="15" y="-10" />
+
+<!-- Комбинация параметров -->
+<Image
+  value="image.png"
+  size="cover"
+  :coordinator="[0, 0, 100, 50]"
+  x="10"
+  y="5"
+/>
 ```

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

@@ -1,28 +1,15 @@
-## Property value
+## Main value
 
-The `value` property is responsible for the main content. It is a universal property that supports multiple types of values, making it as flexible as possible for various use cases.
+The `value` property defines the image content. This universal property supports multiple source types for maximum flexibility.
 
-### Supported value types
+**Supported types:**
 
-- **Icon name** — The name of a built-in or custom icon (if supported by the system).
-- **String (URL)** — A direct link to an image file (e.g., PNG, JPG, SVG, GIF, WebP, etc.).
-- **File object** — A JavaScript `File` object, for example, obtained from `<input type="file">`.
-- **PDF link** — A direct link to a PDF file (the PDF document itself will be displayed inside).
+- **Icon name** — built-in or custom icon from the design system
+- **Image URL** — direct link to file (PNG, JPG, SVG, GIF, WebP, etc.)
+- **File object** — JavaScript File object obtained from `<input type="file">`
+- **PDF document** — direct link to PDF file with automatic display
 
-### Description
-
-- The `value` property is **optional**. If not set, nothing will be displayed.
-- When a `File` object is passed, the component will try to read and display the image or file preview.
-- If a PDF link is provided, the PDF document itself will be displayed inside (for example, with page navigation).
-- If an icon name is provided, the corresponding icon will be displayed.
-- The property is reactive and can be updated dynamically.
-
-### Recommendations
-
-- For the best performance, use optimized image formats (WebP, SVG, etc.).
-- Always validate the file type when accepting user uploads.
-
-### Usage example
+The component automatically detects the source type and selects the optimal display method. When passing a File object, the content is read and previewed. The property is reactive and supports dynamic updates.
 
 ```html
 <!-- Icon by name -->
@@ -31,10 +18,6 @@ The `value` property is responsible for the main content. It is a universal prop
 <!-- Image by URL -->
 <Image value="https://example.com/image.png" />
 
-<!-- Image from a File object -->
-<input type="file" @change="onFileChange" />
-<Image :value="selectedFile" />
-
-<!-- PDF by link -->
-<Image value="https://example.com/file.pdf" />
+<!-- User file -->
+<Image :value="fileFromInput" />
 ```

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

@@ -1,30 +1,15 @@
-## Свойство value
+## Основное значение
 
-Свойство `value` отвечает за основной контент. Это универсальное свойство,
-поддерживающее несколько типов значений, что делает его максимально гибким
-для различных сценариев использования.
+Свойство `value` определяет контент изображения. Это универсальное свойство, поддерживающее несколько типов источников для максимальной гибкости.
 
-### Поддерживаемые типы значений
+**Поддерживаемые типы:**
 
-- **Имя иконки** — Имя встроенной или пользовательской иконки (если поддерживается системой).
-- **Строка (URL)** — Прямая ссылка на файл изображения (например, PNG, JPG, SVG, GIF, WebP и др.).
-- **Объект File** — JavaScript-объект `File`, например, полученный из `<input type="file">`.
-- **Ссылка на PDF** — Прямая ссылка на PDF-файл (будет отображён сам PDF-документ внутри).
+- **Имя иконки** — встроенная или пользовательская иконка из системы дизайна
+- **URL изображения** — прямая ссылка на файл (PNG, JPG, SVG, GIF, WebP и др.)
+- **Объект File** — JavaScript-объект File, полученный из `<input type="file">`
+- **PDF-документ** — прямая ссылка на PDF-файл с автоматическим отображением
 
-### Описание
-
-- Свойство `value` **необязательное**. Если оно не задано, изображение не будет отображено.
-- При передаче объекта `File` будет предпринята попытка прочитать и отобразить изображение или предпросмотр файла.
-- Если передана ссылка на PDF, будет отображён сам PDF-документ внутри (например, с возможностью просмотра страниц).
-- Если передано имя иконки, будет отображена соответствующая иконка.
-- Свойство реактивно и может динамически обновляться.
-
-### Рекомендации
-
-- Для лучшей производительности используйте оптимизированные форматы изображений (WebP, SVG и др.).
-- Всегда проверяйте тип файла при загрузке от пользователя.
-
-### Пример использования
+Компонент автоматически определяет тип источника и выбирает оптимальный способ отображения. При передаче объекта File происходит чтение и предпросмотр содержимого. Свойство реактивно и поддерживает динамическое обновление.
 
 ```html
 <!-- Иконка по имени -->
@@ -33,10 +18,6 @@
 <!-- Изображение по URL -->
 <Image value="https://example.com/image.png" />
 
-<!-- Изображение из объекта File -->
-<input type="file" @change="onFileChange" />
-<Image :value="selectedFile" />
-
-<!-- PDF по ссылке -->
-<Image value="https://example.com/file.pdf" />
+<!-- Файл от пользователя -->
+<Image :value="fileFromInput" />
 ```

package/src/media/mdx/Image/wikiMdxImage.ts

@@ -1,5 +1,7 @@
 import type { StorybookComponentsMdxItem } from '../../../types/storybookTypes'
 
+import imageEn from './image.en.mdx'
+import imageRu from './image.ru.mdx'
 import valueEn from './value.en.mdx'
 import valueRu from './value.ru.mdx'
 import sizeEn from './size.en.mdx'
@@ -10,14 +12,16 @@ import adaptiveRu from './adaptive.ru.mdx'
 import eventLoadEn from './event.load.en.mdx'
 import eventLoadRu from './event.load.ru.mdx'
 
-import exposeTypeEn from './expose.type.en.mdx'
-import exposeTypeRu from './expose.type.ru.mdx'
-import exposeDataEn from './expose.data.en.mdx'
-import exposeDataRu from './expose.data.ru.mdx'
+import exposeEn from './expose.en.mdx'
+import exposeRu from './expose.ru.mdx'
 
 export const wikiMdxImage: StorybookComponentsMdxItem = {
   name: 'Image',
   descriptions: {
+    'image': {
+      en: imageEn,
+      ru: imageRu
+    },
     'value': {
       en: valueEn,
       ru: valueRu
@@ -34,13 +38,9 @@ export const wikiMdxImage: StorybookComponentsMdxItem = {
       en: eventLoadEn,
       ru: eventLoadRu
     },
-    'expose.type': {
-      en: exposeTypeEn,
-      ru: exposeTypeRu
-    },
-    'expose.data': {
-      en: exposeDataEn,
-      ru: exposeDataRu
+    'expose': {
+      en: exposeEn,
+      ru: exposeRu
     }
   }
 }

package/src/media/mdx/List/event.close.en.mdx

@@ -1,11 +1,8 @@
 ### `close`
 
-Event fired when the list requests closing of the active context (menu/group/window).
+Event fires when attempting to close the list after navigation has reached the root level.
 
-```ts
-function onClose (): void {
-  // handle list close
-}
-```
-
-The event does not pass any parameters.
+**When it fires:**
+- Pressing the **Escape** key at the root level of the list
+- Pressing the **←** (left arrow) key when there are no open submenus/groups
+- Attempting to navigate back when there are no nested items

package/src/media/mdx/List/event.close.ru.mdx

@@ -1,11 +1,8 @@
 ### `close`
 
-Событие, которое срабатывает при запросе закрытия активного контекста списка (меню/группы/окна).
+Событие срабатывает при попытке закрыть список, когда навигация достигла корневого уровня.
 
-```ts
-function onClose (): void {
-  // обработать закрытие списка
-}
-```
-
-Событие не передаёт параметры.
+**Когда срабатывает:**
+- Нажатие клавиши **Escape** на корневом уровне списка
+- Нажатие клавиши **←** (стрелка влево), когда нет открытых подменю/групп
+- Попытка навигации назад при отсутствии вложенных элементов

package/src/media/mdx/List/list.en.mdx

@@ -1,22 +1,64 @@
-The List component is a powerful interactive list with support for hierarchical data, keyboard navigation, and search functionality. It is designed to display structured data with navigation capabilities, item selection, and interaction through keyboard and mouse.
+A component for creating interactive lists with support for hierarchical data, keyboard navigation, and search functionality.
 
-## Core Features
+List manages the display of structured data with navigation capabilities, item selection, and interaction through keyboard and mouse. The component supports various item types (regular items, groups, menus, dividers, subtitles, HTML content), automatically handles complex hierarchical structures, and provides intuitive navigation. The built-in search system works in real-time with match highlighting across the entire data hierarchy.
 
-List supports various item types: regular items, groups, menus, separators, and subtitles. The component automatically handles complex hierarchical structures and provides intuitive navigation between elements.
+**Key features:**
 
-## Keyboard Navigation
+- Various item types (item, group, menu, line, subtitle, html)
+- Hierarchical structure with nested groups and menus
+- Full keyboard navigation (↑/↓, Enter, →, ←)
+- Built-in real-time search with match highlighting
+- Item selection control via v-model:selected
+- Focus control via v-model:focus
+- Lightweight mode for large lists (lite)
+- Display axis configuration (x/y) and dividers
+- Click and menu close events
 
-The component supports full keyboard navigation:
-- **↑/↓** - navigate between items
-- **Enter/→** - open groups/menus or select item
-- **←** - close groups/menus
-- **Type text** - search through items
-- **Backspace** - clear search
+**Typical use cases:**
 
-## Search and Highlighting
+- Navigation menus and option lists
+- Dropdown lists with hierarchical structure
+- Product and category catalogs
+- Settings lists with grouping
+- Context menus with submenus
+- File and folder lists
+- Filters with multiple selection
 
-Built-in search functionality allows finding items in real-time with automatic highlighting of matches. Search works across the entire data hierarchy, including nested groups and menus.
+```html
+<script setup>
+import { ref } from 'vue'
 
-## Performance
+const selected = ref(['item2'])
+const focus = ref(null)
 
-For working with large datasets, the component provides a lightweight rendering mode that automatically activates when the specified threshold of item count is exceeded, ensuring high performance without losing functionality.
+const listData = ref([
+  { label: 'First item', value: 'item1' },
+  { label: 'Second item', value: 'item2' },
+  { type: 'line' },
+  { type: 'subtitle', label: 'Item group' },
+  {
+    label: 'Group with submenu',
+    value: 'group1',
+    type: 'group',
+    list: [
+      { label: 'Nested item 1', value: 'nested1' },
+      { label: 'Nested item 2', value: 'nested2' }
+    ]
+  }
+])
+
+const handleClick = (event) => {
+  console.log('Item clicked:', event.detail.value)
+}
+</script>
+
+<template>
+  <List
+    v-model:selected="selected"
+    v-model:focus="focus"
+    :list="listData"
+    highlight="text"
+    @click="handleClick"
+  />
+</template>
+```