@dxtmisha/wiki 0.39.3 → 0.39.5

package/src/media/functional/ui/properties/quick-start/quick-start.ru.mdx

@@ -1,78 +1,108 @@
 import {Meta} from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/ru/# UI/properties/Быстрый старт'/>
+<Meta title='@dxtmisha/ru/# UI/properties/! Быстрый старт'/>
 
 # Быстрый старт
 
-Данное руководство демонстрирует основы внедрения кодогенерации для вашего UI-компонента с помощью `properties.json`.
+Данное руководство поможет вам быстро освоить работу с файлом `properties.json` на примере типичного UI-компонента. Файл является **единым источником истины** — из него генерируются как стили (SCSS), так и программный интерфейс (TypeScript Props).
 
-## 1. Базовые стили
+## 1. Базовые свойства и токены
 
-Простейшая конфигурация строится на прямом соответствии ключей физическим CSS-свойствам. Добавим базовый фон и отступы:
+Вместо фиксированных значений (HEX, px) всегда используйте систему дизайн-токенов `{sys...}`. Это гарантирует поддержку тем и консистентность.
 
 ```json
 {
-  "background-color": "#cccccc",
-  "padding": "12px 24px"
+  "padding": "{sys.spacing.md}",
+  "background-color": "{sys.palette.surface}",
+  "border-radius": "{sys.rounded.md}"
 }
 ```
 
-Генератор свойств автоматически сформирует следующий SCSS-класс (название класса выводится из базовых настроек вашей дизайн-системы):
+**Результат (SCSS):**
 ```scss
 .component {
-  background-color: #cccccc;
-  padding: 12px 24px;
+  padding: var(--sys-spacing-md);
+  background-color: var(--sys-palette-surface);
+  border-radius: var(--sys-rounded-md);
 }
 ```
 
-## 2. Генерация CSS переменных
+## 2. Состояния (States)
 
-Если вам нужно, чтобы свойство выводилось как динамическая CSS-переменная (например, для использования в скриптах или темах), используйте конфигурационный объект с флагом `_var: true` или `_type: "var"`.
+Для описания интерактивности (hover, focus, active, disabled) используйте зарезервированные ключи.
 
 ```json
 {
-  "border-radius": {
-    "_var": true,
-    "value": "8px"
+  "hover": {
+    "background-color": "{sys.palette.surfaceVariant}"
+  },
+  "disabled": {
+    "opacity": "{sys.opacity.disabled}",
+    "cursor": "not-allowed"
   }
 }
 ```
 
-Результат:
+**Результат (SCSS):**
 ```scss
 .component {
-  --component-border-radius: 8px;
-  border-radius: var(--component-border-radius);
+  &:hover { background-color: var(--sys-palette-surfaceVariant); }
+  &:disabled { 
+    opacity: var(--sys-opacity-disabled);
+    cursor: not-allowed;
+  }
 }
 ```
 
-## 3. Состояния и модификаторы
+## 3. Модификаторы (Маркер `~`)
 
-Генератор автоматически транслирует вложенные древовидные структуры в псевдоклассы (состояния) и БЭМ-модификаторы:
+Чтобы создать вариацию компонента (например, `primary` или `secondary`), используйте префикс `~`. Такие ключи автоматически преобразуются в **Props** во Vue/React и в BEM-модификаторы в CSS.
 
 ```json
 {
-  "hover": {
-    "background-color": "#aaaaaa"
-  },
-  "~active": {
-    "background-color": "#555555"
+  "~primary": {
+    "color": "{sys.palette.onPrimary}",
+    "background-color": "{sys.palette.primary}",
+    "_default": true
   }
 }
 ```
 
-Результат:
+**Результат (SCSS):**
 ```scss
 .component {
-  &:hover {
-    background-color: #aaaaaa;
+  &--primary {
+    color: var(--sys-palette-onPrimary);
+    background-color: var(--sys-palette-primary);
   }
-  
-  /* БЭМ модификатор для Vue Props */
-  &--active {
-    background-color: #555555;
+}
+```
+
+**Результат (TypeScript Props):**
+```typescript
+type PropsToken = {
+  primary?: boolean // Генерируется автоматически
+}
+```
+
+## 4. Кастомные переменные (`_var`)
+
+Если вам нужно, чтобы свойство было доступно как CSS-переменная для внешнего управления или использования в скриптах, добавьте флаг `_var: true`.
+
+```json
+{
+  "height": {
+    "value": "48px",
+    "_var": true
   }
 }
 ```
 
-> **Важно:** Для более сложной конфигурации, работы с дизайн-токенами `{sys...}` и автоматической типизации интерфейса, изучите раздел **Описание структуры**.
+**Результат (SCSS):**
+```scss
+.component {
+  --component-height: 48px;
+  height: var(--component-height);
+}
+```
+

package/src/media/functional/ui/properties/quick-start/quick-start.vi.mdx

@@ -1,78 +1,108 @@
 import {Meta} from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/vi/# UI/properties/Bắt đầu nhanh'/>
+<Meta title='@dxtmisha/vi/# UI/properties/! Bắt đầu nhanh'/>
 
 # Bắt đầu nhanh
 
-Hướng dẫn này cung cấp nền tảng thiết lập gen-code cơ bản cho Component UI của bạn thông qua tệp hệ thống `properties.json`.
+Hướng dẫn này giúp bạn nhanh chóng nắm vững cách làm việc với tệp `properties.json` thông qua ví dụ về một UI component điển hình. Tệp này đóng vai trò là **nguồn chân lý duy nhất (single source of truth)** — từ đó cả style (SCSS) và giao diện lập trình (TypeScript Props) đều được tạo ra tự động.
 
-## 1. Thiết lập CSS cơ bản
+## 1. Thuộc tính cơ bản và Tokens
 
-Cấu hình dạng sơ cấp trực tiếp dựa dẫm vào gốc thuộc tính HTML CSS thông dụng làm khoá mã. Thiết đặt thử màu nền (background) và mã tuỳ chỉnh viền viền (padding):
+Thay vì sử dụng các giá trị cố định (HEX, px), hãy luôn sử dụng hệ thống design token `{sys...}`. Điều này đảm bảo hỗ trợ thay đổi giao diện (themes) và tính nhất quán của thiết kế.
 
 ```json
 {
-  "background-color": "#cccccc",
-  "padding": "12px 24px"
+  "padding": "{sys.spacing.md}",
+  "background-color": "{sys.palette.surface}",
+  "border-radius": "{sys.rounded.md}"
 }
 ```
 
-Máy biên dịch framework tiến hành trích xuất tự động qua block code hệ quy chiếu SCSS chuẩn của module (khóa parent):
+**Kết quả (SCSS):**
 ```scss
 .component {
-  background-color: #cccccc;
-  padding: 12px 24px;
+  padding: var(--sys-spacing-md);
+  background-color: var(--sys-palette-surface);
+  border-radius: var(--sys-rounded-md);
 }
 ```
 
-## 2. Khai báo biến CSS Variables Động
+## 2. Các trạng thái (States)
 
-Để đảm bảo giá trị giao diện có thể dễ dàng gọi tự động phục vụ đổi tham số Theme linh động ngay trên client, khai báo cấu trúc theo chuẩn Object mở rộng gắn cờ thuộc tính `_var: true`.
+Sử dụng các khóa đã được quy định sẵn để mô tả tính tương tác (hover, focus, active, disabled).
 
 ```json
 {
-  "border-radius": {
-    "_var": true,
-    "value": "8px"
+  "hover": {
+    "background-color": "{sys.palette.surfaceVariant}"
+  },
+  "disabled": {
+    "opacity": "{sys.opacity.disabled}",
+    "cursor": "not-allowed"
   }
 }
 ```
 
-Kết quả gen-code block SCSS:
+**Kết quả (SCSS):**
 ```scss
 .component {
-  --component-border-radius: 8px;
-  border-radius: var(--component-border-radius);
+  &:hover { background-color: var(--sys-palette-surfaceVariant); }
+  &:disabled { 
+    opacity: var(--sys-opacity-disabled);
+    cursor: not-allowed;
+  }
 }
 ```
 
-## 3. Tổ hợp Trạng thái và Modifiers BEM
+## 3. Các biến thể (Dấu hiệu `~`)
 
-Tiến trình phân bổ tự động nội suy nhóm mảng cho phần nhánh cấp thấp thành Pseudo-classes chuột hay các biến thể modifiers class:
+Để tạo ra một biến thể của component (ví dụ: `primary` hoặc `secondary`), hãy sử dụng tiền tố `~`. Các khóa này sẽ tự động được chuyển đổi thành **Props** trong Vue/React và các BEM modifiers trong CSS.
 
 ```json
 {
-  "hover": {
-    "background-color": "#aaaaaa"
-  },
-  "~active": {
-    "background-color": "#555555"
+  "~primary": {
+    "color": "{sys.palette.onPrimary}",
+    "background-color": "{sys.palette.primary}",
+    "_default": true
   }
 }
 ```
 
-Thành phẩm sau quy trình module framework nhận được:
+**Kết quả (SCSS):**
 ```scss
 .component {
-  &:hover {
-    background-color: #aaaaaa;
+  &--primary {
+    color: var(--sys-palette-onPrimary);
+    background-color: var(--sys-palette-primary);
   }
-  
-  /* Chuỗi BEM modifier tự động chuẩn bị map prop TypeScript */
-  &--active {
-    background-color: #555555;
+}
+```
+
+**Kết quả (TypeScript Props):**
+```typescript
+type PropsToken = {
+  primary?: boolean // Được tạo tự động
+}
+```
+
+## 4. Các biến tùy chỉnh (`_var`)
+
+Nếu bạn cần một thuộc tính có sẵn dưới dạng biến CSS để điều khiển từ bên ngoài hoặc sử dụng trong script, hãy thêm cờ `_var: true`.
+
+```json
+{
+  "height": {
+    "value": "48px",
+    "_var": true
   }
 }
 ```
 
-> **Ghi chú quan trọng:** Để phát huy sức mạnh gán biến ảo Token-System format (`{sys...}`) bằng cơ chế kết xuất nhanh Interface Types, bạn hãy tra cứu sâu thư viện **Mô tả cấu trúc**.
+**Kết quả (SCSS):**
+```scss
+.component {
+  --component-height: 48px;
+  height: var(--component-height);
+}
+```
+

package/src/media/functional/ui/properties/type-media/type-media.en.mdx

@@ -54,3 +54,32 @@ Adaptive queries can be initialized using the `|` separator shortcut (e.g., `med
   }
 }
 ```
+
+### Group Formation (Media Group)
+
+The specialized types `media-group`, `media-max-group`, `container-group`, and `container-max-group` allow for the automatic generation of a set of adaptive rules for all available breakpoints defined in the system.
+
+This eliminates the need to manually write each media query when the adaptation logic is the same for different sizes but must be encapsulated into separate selectors.
+
+**Example Configuration (`properties.json`):**
+```json
+{
+  "button": {
+    "group|icon": {
+      "_type": "media-group",
+      "padding": "8px"
+    }
+  }
+}
+```
+
+**Compiled Output (SCSS):**
+When using `media-group`, the system creates nested classes for each breakpoint by adding a suffix (e.g., `iconSm`, `iconMd`):
+```scss
+.button {
+  &--iconSm { @media (min-width: 640px) { padding: 8px; } }
+  &--iconMd { @media (min-width: 768px) { padding: 8px; } }
+  &--iconLg { @media (min-width: 1024px) { padding: 8px; } }
+  // and so on for all breakpoints...
+}
+```

package/src/media/functional/ui/properties/type-media/type-media.ru.mdx

@@ -54,3 +54,32 @@ import {Meta} from '@storybook/addon-docs/blocks'
   }
 }
 ```
+
+### Групповое формирование (Media Group)
+
+Специальные типы `media-group`, `media-max-group`, `container-group` и `container-max-group` позволяют автоматически генерировать набор адаптивных правил для всех доступных точек останова (breakpoints), определенных в системе.
+
+Это избавляет от необходимости вручную прописывать каждый медиа-запрос, если логика адаптации одинакова для разных размеров, но должна быть инкапсулирована в отдельные селекторы.
+
+**Пример конфигурации (`properties.json`):**
+```json
+{
+  "button": {
+    "group|icon": {
+      "_type": "media-group",
+      "padding": "8px"
+    }
+  }
+}
+```
+
+**Результат генерации (SCSS):**
+При использовании `media-group` система создаст вложенные классы для каждого брейкпоинта, добавляя суффикс (например, `iconSm`, `iconMd`):
+```scss
+.button {
+  &--iconSm { @media (min-width: 640px) { padding: 8px; } }
+  &--iconMd { @media (min-width: 768px) { padding: 8px; } }
+  &--iconLg { @media (min-width: 1024px) { padding: 8px; } }
+  // и так далее для всех точек останова...
+}
+```

package/src/media/functional/ui/properties/type-media/type-media.vi.mdx

@@ -54,3 +54,32 @@ Truy vấn thích ứng có thể được thiết lập thông qua phím tắt
   }
 }
 ```
+
+### Tạo nhóm thích ứng (Media Group)
+
+Các loại đặc biệt `media-group`, `media-max-group`, `container-group`, và `container-max-group` cho phép tự động tạo ra một tập hợp các quy tắc thích ứng cho tất cả các điểm dừng (breakpoints) có sẵn được định nghĩa trong hệ thống.
+
+Điều này giúp loại bỏ việc phải viết thủ công từng truy vấn media khi logic thích ứng giống nhau cho các kích thước khác nhau nhưng cần được đóng gói vào các bộ chọn (selectors) riêng biệt.
+
+**Ví dụ cấu hình (`properties.json`):**
+```json
+{
+  "button": {
+    "group|icon": {
+      "_type": "media-group",
+      "padding": "8px"
+    }
+  }
+}
+```
+
+**Kết quả Biên dịch (SCSS):**
+Khi sử dụng `media-group`, hệ thống sẽ tạo ra các lớp lồng nhau cho mỗi breakpoint bằng cách thêm hậu tố (ví dụ: `iconSm`, `iconMd`):
+```scss
+.button {
+  &--iconSm { @media (min-width: 640px) { padding: 8px; } }
+  &--iconMd { @media (min-width: 768px) { padding: 8px; } }
+  &--iconLg { @media (min-width: 1024px) { padding: 8px; } }
+  // và cứ thế cho tất cả các breakpoints...
+}
+```

package/src/media/mdx/Accordion/accordion.en.mdx

@@ -0,0 +1,59 @@
+## Description
+
+Expandable container for organizing content with smooth opening and closing animations, simplifying information structuring in the interface.
+
+Accordion allows creating expandable sections with automatic animations, interactive header, and state management via v-model. The component supports padding configuration, visual dividers, and content customization through slots.
+
+**Key features:**
+
+- Smooth expand and collapse animations
+- Header with label, description, and icons
+- State management via v-model:open
+- Programmatic control (toggle, toOpen, toClose)
+- Internal padding configuration (padding)
+- Visual divider between sections
+- Customization via head and default slots
+
+**Common use cases:**
+
+- FAQ sections
+- Settings panels
+- Product filters
+- Information blocks
+- Menus with subsections
+
+```html
+<script setup>
+import { ref } from 'vue'
+
+const isOpen = ref(false)
+</script>
+
+<template>
+  <!-- Basic accordion -->
+  <Accordion label="Question 1">
+    <p>Answer to the question.</p>
+  </Accordion>
+
+  <!-- With state management -->
+  <Accordion
+    v-model:open="isOpen"
+    label="Settings"
+    icon="settings"
+  >
+    <p>Settings content.</p>
+  </Accordion>
+
+  <!-- With custom header -->
+  <Accordion>
+    <template #head>
+      <div>Custom header</div>
+    </template>
+    <template #default>
+      <p>Section content.</p>
+    </template>
+  </Accordion>
+</template>
+```
+
+> Accordion is a component for creating expandable sections with animation support, state management, and flexible customization.

package/src/media/mdx/Accordion/accordion.ru.mdx

@@ -0,0 +1,59 @@
+## Описание
+
+Раскрывающийся контейнер для организации контента с плавными анимациями открытия и закрытия, упрощающий структурирование информации в интерфейсе.
+
+Accordion позволяет создавать раскрывающиеся секции с автоматическими анимациями, интерактивным заголовком и возможностью управления через v-model. Компонент поддерживает настройку отступов, визуальных разделителей и кастомизацию содержимого через слоты.
+
+**Основные возможности:**
+
+- Плавные анимации раскрытия и сворачивания
+- Заголовок с меткой, описанием и иконками
+- Управление состоянием через v-model:open
+- Программное управление (toggle, toOpen, toClose)
+- Настройка внутренних отступов (padding)
+- Визуальный разделитель между секциями
+- Кастомизация через слоты head и default
+
+**Типичные сценарии использования:**
+
+- FAQ секции
+- Панели настроек
+- Фильтры товаров
+- Информационные блоки
+- Меню с подразделами
+
+```html
+<script setup>
+import { ref } from 'vue'
+
+const isOpen = ref(false)
+</script>
+
+<template>
+  <!-- Базовый аккордеон -->
+  <Accordion label="Вопрос 1">
+    <p>Ответ на вопрос.</p>
+  </Accordion>
+
+  <!-- С управлением состоянием -->
+  <Accordion
+    v-model:open="isOpen"
+    label="Настройки"
+    icon="settings"
+  >
+    <p>Содержимое настроек.</p>
+  </Accordion>
+
+  <!-- С кастомным заголовком -->
+  <Accordion>
+    <template #head>
+      <div>Свой заголовок</div>
+    </template>
+    <template #default>
+      <p>Содержимое секции.</p>
+    </template>
+  </Accordion>
+</template>
+```
+
+> Accordion — компонент для создания раскрывающихся секций с поддержкой анимаций, управления состоянием и гибкой кастомизации.

package/src/media/mdx/Accordion/slots.en.mdx

@@ -0,0 +1,9 @@
+- `default(props: MotionTransformControlItem): any` — Slot for placing the main accordion content that appears when the section is expanded.
+
+> **MotionTransformControlItem:**
+> - `isOpen: ComputedRef<boolean>` — reactive open state.
+> - `isShow: ComputedRef<boolean>` — visible or preparing to show.
+> - `classes: MotionTransformClassList` — helper CSS classes.
+> - `idControl: string` — identifier for the control element.
+> - `idBody: string` — identifier for the body element.
+> - `binds: AriaRoleControlPropsInclude` — binding attributes for accessibility.

package/src/media/mdx/Accordion/slots.ru.mdx

@@ -0,0 +1,9 @@
+- `default(props: MotionTransformControlItem): any` — Слот для размещения основного содержимого аккордеона, которое появляется при раскрытии секции.
+
+> **MotionTransformControlItem:**
+> - `isOpen: ComputedRef<boolean>` — реактивное состояние открытия.
+> - `isShow: ComputedRef<boolean>` — видим либо готовится к показу.
+> - `classes: MotionTransformClassList` — вспомогательные CSS‑классы.
+> - `idControl: string` — идентификатор элемента управления.
+> - `idBody: string` — идентификатор элемента тела.
+> - `binds: AriaRoleControlPropsInclude` — атрибуты привязки для доступности.

package/src/media/mdx/Accordion/wikiMdxAccordion.ts

@@ -0,0 +1,25 @@
+import type { StorybookComponentsMdxItem } from '../../../types/storybookTypes'
+
+import accordionEn from './accordion.en.mdx'
+import accordionRu from './accordion.ru.mdx'
+import slotsEn from './slots.en.mdx'
+import slotsRu from './slots.ru.mdx'
+
+/**
+ * MDX files for Accordion component
+ *
+ * MDX файлы для компонента Accordion
+ */
+export const wikiMdxAccordion: StorybookComponentsMdxItem = {
+  name: 'Accordion',
+  descriptions: {
+    accordion: {
+      en: accordionEn,
+      ru: accordionRu
+    },
+    slots: {
+      en: slotsEn,
+      ru: slotsRu
+    }
+  }
+}

package/src/media/mdx/ActionSheet/actionSheet.en.mdx

@@ -0,0 +1,61 @@
+Component for creating mobile-optimized action panels that slide up from the bottom of the screen with smooth animation.
+
+ActionSheet is a specialized wrapper over the Window component with a preset `actionSheet` adaptive mode. The component automatically positions itself at the bottom of the screen and slides up when opened, following iOS and Material Design mobile interface patterns. Supports swipe gestures for closing, integration with the Bars component for the header, and automatic focus management.
+
+**Key features:**
+
+- Positioning at the bottom of the screen with slide-up animation
+- Touch gesture support for closing by swiping down
+- Integration with Bars for header display
+- Automatic background blocking when opened
+- Closing by clicking on overlay or close button
+- Lifecycle events (opening, closing)
+- Slot support for content customization
+- Adaptive height based on content size
+
+**Common use cases:**
+
+- Action menus for mobile applications
+- Option and selection lists
+- Forms and filters on mobile devices
+- Context menus for touch interfaces
+- Confirmations and notifications
+
+```html
+<script setup>
+import { ref } from 'vue'
+
+const isOpen = ref(false)
+
+const handleAction = (action) => {
+  console.log('Selected action:', action)
+  isOpen.value = false
+}
+</script>
+
+<template>
+  <button @click="isOpen = true">Open Actions</button>
+
+  <ActionSheet
+    v-model:open="isOpen"
+    :touchClose="true"
+  >
+    <template #title>
+      <h3>Choose Action</h3>
+    </template>
+
+    <template #default>
+      <div class="action-list">
+        <button @click="handleAction('share')">Share</button>
+        <button @click="handleAction('copy')">Copy Link</button>
+        <button @click="handleAction('download')">Download</button>
+      </div>
+    </template>
+
+    <template #footer>
+      <button @click="isOpen = false">Cancel</button>
+    </template>
+  </ActionSheet>
+</template>
+```
+