@dxtmisha/wiki 0.39.4 → 0.39.5

package/src/media/descriptions/wikiDescriptionsWindow.ts

@@ -0,0 +1,241 @@
+import type { StorybookComponentsDescriptionItem } from '../../types/storybookTypes'
+
+/**
+ * Descriptions for Window component properties
+ *
+ * Описания свойств компонента Window
+ */
+export const wikiDescriptionsWindow: StorybookComponentsDescriptionItem = {
+  name: 'Window',
+  description: {
+    en: 'Flexible modal and popup window component with advanced positioning and animation capabilities',
+    ru: 'Гибкий компонент модального и всплывающего окна с расширенными возможностями позиционирования и анимации'
+  },
+  possibilities: {
+    en: [
+      'modal and contextual window display modes',
+      'intelligent positioning system with automatic collision detection',
+      'smooth opening and closing animations with customizable transitions',
+      'static mode for embedded window components',
+      'persistent window state management',
+      'automatic scroll handling and content overflow management',
+      'keyboard navigation and accessibility support',
+      'event-driven architecture with comprehensive lifecycle hooks',
+      'integration with scrollbar and image components',
+      'responsive design with mobile and desktop optimization'
+    ],
+    ru: [
+      'режимы отображения модальных и контекстных окон',
+      'интеллектуальная система позиционирования с автоматическим определением коллизий',
+      'плавные анимации открытия и закрытия с настраиваемыми переходами',
+      'статический режим для встроенных компонентов окон',
+      'управление постоянным состоянием окна',
+      'автоматическая обработка прокрутки и управление переполнением контента',
+      'навигация с клавиатуры и поддержка доступности',
+      'событийно-ориентированная архитектура с комплексными хуками жизненного цикла',
+      'интеграция с компонентами скроллбара и изображений',
+      'адаптивный дизайн с оптимизацией для мобильных устройств и десктопа'
+    ]
+  },
+  import: [
+    'import { ref } from \'vue\''
+  ],
+  render: `
+      <DesignComponent v-bind="args">
+        <template #control="{binds}">
+          <button class="wiki-storybook-button" v-bind="binds">Open Window</button>
+        </template>
+
+        <template #title>
+          <h3 class="wiki-storybook-item--padding">Window Component Demonstration</h3>
+        </template>
+
+        <template #default>
+          <div class="wiki-storybook-item--padding">
+            <h4>Advanced Window System</h4>
+            <p>This window component represents a sophisticated approach to modal and popup interfaces in modern web applications. It provides a comprehensive solution for displaying overlaid content with intelligent positioning, smooth animations, and extensive customization options.</p>
+
+            <p>The component automatically handles complex scenarios such as viewport boundaries, scroll positioning, and responsive behavior across different screen sizes. Whether used for modal dialogs, dropdown menus, tooltips, or contextual panels, the window component adapts to various use cases while maintaining consistent behavior and appearance.</p>
+
+            <h4>Key Features and Capabilities</h4>
+            <p>The window system includes advanced features such as automatic positioning algorithms that prevent content from appearing outside viewport boundaries, smooth transition animations that enhance user experience, and comprehensive event handling for various interaction patterns including keyboard navigation and focus management.</p>
+
+            <p>Integration with other components such as scrollbars and images is seamless, allowing for rich content presentation within window containers. The component supports both programmatic and declarative control patterns, making it suitable for different development approaches and architectural requirements.</p>
+
+            <h4>Technical Architecture</h4>
+            <p>Built with a modular composition-based architecture, the window component consists of multiple specialized subcomponents that handle specific aspects of functionality. This includes separate managers for positioning, events, styles, animations, and state persistence, ensuring maintainable and testable code.</p>
+
+            <p>The component follows modern Vue.js patterns with reactive state management, composable APIs, and TypeScript support throughout. Performance is optimized through intelligent rendering strategies and minimal DOM manipulation, ensuring smooth operation even in complex applications with multiple concurrent windows.</p>
+          </div>
+        </template>
+
+        <template #footer="{classesWindow}">
+          <div class="wiki-storybook-flex wiki-storybook-item--padding">
+            <button :class="classesWindow.close" class="wiki-storybook-button wiki-storybook-button--text">Cancel</button>
+            <button class="wiki-storybook-button">Confirm</button>
+          </div>
+        </template>
+      </DesignComponent>
+    `,
+  stories: [
+    {
+      id: 'WindowStaticMode',
+      name: {
+        en: 'Static Mode',
+        ru: 'Статический режим'
+      },
+      template: `
+        <DesignComponent :staticMode="true" adaptive="static">
+          <template #default>
+            <h4>Static Mode Window</h4>
+            <p>This window uses <code>staticMode: true</code>.</p>
+            <p>Content displays immediately without animations or modal positioning.</p>
+
+            <div class="wiki-storybook-info">
+              <strong>Static mode features:</strong>
+              <ul>
+                <li>No animations</li>
+                <li>Embedded in document flow</li>
+                <li>Always visible</li>
+              </ul>
+            </div>
+          </template>
+        </DesignComponent>
+      `
+    },
+    {
+      id: 'WindowAxis',
+      name: {
+        en: 'Axis positioning',
+        ru: 'Позиционирование по оси'
+      },
+      template: `
+        <div class="wiki-storybook-flex wiki-storybook-gap">
+          <!-- Axis: x -->
+          <DesignComponent axis="x" adaptive="menu" :indent="8">
+            <template #control="{binds}">
+              <button class="wiki-storybook-button" v-bind="binds">Open (axis: x)</button>
+            </template>
+            <template #default>
+              <div class="wiki-storybook-item--padding">
+                <strong>axis = x</strong>
+                <p>Window aligns horizontally (left/right) near the trigger.</p>
+              </div>
+            </template>
+          </DesignComponent>
+
+          <!-- Axis: y -->
+          <DesignComponent axis="y" adaptive="menu" :indent="8">
+            <template #control="{binds}">
+              <button class="wiki-storybook-button" v-bind="binds">Open (axis: y)</button>
+            </template>
+            <template #default>
+              <div class="wiki-storybook-item--padding">
+                <strong>axis = y</strong>
+                <p>Window aligns vertically (top/bottom) near the trigger.</p>
+              </div>
+            </template>
+          </DesignComponent>
+
+          <!-- Axis: on -->
+          <DesignComponent axis="on" adaptive="menu" overElement=".axis-on-target">
+            <template #control="{binds}">
+              <button class="wiki-storybook-button" v-bind="binds">Open (axis: on)</button>
+            </template>
+            <template #default>
+              <div class="wiki-storybook-item--padding">
+                <strong>axis = on</strong>
+                <p>Window positions over the target element; scroll adjusts to keep it visible.</p>
+                <ul style="max-height: 160px; overflow: auto; margin: 8px 0; padding-left: 20px;">
+                  <li>Item 1</li>
+                  <li>Item 2</li>
+                  <li>Item 3</li>
+                  <li>Item 4</li>
+                  <li class="axis-on-target"><strong>Focused item (target)</strong></li>
+                  <li>Item 6</li>
+                  <li>Item 7</li>
+                  <li>Item 8</li>
+                  <li>Item 9</li>
+                  <li>Item 10</li>
+                </ul>
+              </div>
+            </template>
+          </DesignComponent>
+        </div>
+      `
+    },
+    {
+      id: 'WindowVModel',
+      name: {
+        en: 'Two-way binding (v-model)',
+        ru: 'Двусторонняя привязка (v-model)'
+      },
+      setup: `
+      return {
+        open: ref(false)
+      }
+      `,
+      template: `
+        <button class="wiki-storybook-button" @click="open = true">Open via v-model ({{ open }})</button>
+
+        <DesignComponent v-model:open="open">
+          <div class="wiki-storybook-item--padding">Your content here</div>
+        </DesignComponent>
+      `
+    }
+  ],
+  documentation: {
+    body: `
+<StorybookDescriptions componentName={'Window'} type={'window'}/>
+<StorybookDescriptions componentName={'Window'} type={'classes'}/>
+<StorybookDescriptions componentName={'Window'} type={'staticMode'}/>
+<Canvas of={Component.WindowStaticMode}/>
+<StorybookDescriptions componentName={'Window'} type={'axis'}/>
+<Canvas of={Component.WindowAxis}/>
+<StorybookDescriptions componentName={'Window'} type={'v-model'}/>
+<Canvas of={Component.WindowVModel}/>
+<StorybookDescriptions componentName={'Window'} type={'hooks'}/>
+    `,
+    events: `
+<StorybookDescriptions componentName={'Window'} type={'event.window'}/>
+<StorybookDescriptions componentName={'Scrollbar'} type={'emits-include'}/>
+<StorybookDescriptions componentName={'Image'} type={'event.load'}/>
+    `,
+    expose: `
+<StorybookDescriptions componentName={'Window'} type={'expose'}/>
+    `,
+    slots: `
+<StorybookDescriptions componentName={'Window'} type={'slots'}/>
+    `
+  },
+  ai: {
+    render: `
+      <div :class="classDemo.item">
+        <Window embedded open v-bind="args">
+            <template #control="{ binds }">
+              <button v-bind="binds">Open Window</button>
+            </template>
+            <template #title>
+              <h3>Window Title</h3>
+            </template>
+            <template #default>
+              <p>Window content goes here. This is a demonstration of the window component capabilities.</p>
+              <p>It can contain text, images, forms, or any other content.</p>
+            </template>
+            <template #footer>
+              <div>
+                <button>Cancel</button>
+                <button>Save</button>
+              </div>
+            </template>
+          </Window>
+      </div>
+    `,
+    description: `
+Versatile high-performance container orchestration system for Modals, Popups, Dropdowns, and Cards. Automatically manages complex DOM interactions including z-index hierarchy, focus trapping, teleportation, and body scroll locking.
+Features an intelligent multi-axis positioning engine (vertical, horizontal, or overlay) with automated viewport collision detection and obstacle avoidance. Includes a full suite of lifecycle hooks, advanced animation management, and integrated support for Scrollbar and Image components within its content area.
+Controlled via the v-model:open prop and utilizing the #control, #title, #default, and #footer slots for modular layout. Use as a foundational building block for any overlaid or contextual interface requirement that exceeds the logic of standard Modal or Menu components.
+    `,
+    hide: true
+  }
+}

package/src/media/functional/ui/properties/about/about.en.mdx

@@ -1,20 +1,21 @@
 import {Meta} from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/en/# UI/properties/! About the module'/>
+<Meta title='@dxtmisha/en/# UI/properties/! About properties.json'/>
 
-# Properties
+# Configuration (properties.json)
 
-The `Properties` module is designed for declarative management of design system styles using JSON configurations. Component developers no longer need to manually write SCSS code for states, media queries, and variables—instead, all design tokens are described in a `properties.json` file.
+The `properties.json` file is a declarative manifest of your component. In it, you describe the structure, styles, states, and parameters, which are then automatically transformed into production-ready SCSS code and typed TypeScript interfaces (`props.ts`).
 
-## Why do we need this file?
+## How to work with this file?
 
-In every scalable UI component library, there is a common problem of managing spacing, colors, and states (hover, focus, disabled). Creating a `properties.json` file allows to:
-- Centralize all tokens in one clear place next to the component.
-- Automatically generate typed props for Vue/React from it.
-- Obtain ready-to-use SCSS classes, variables, and themes without code duplication.
+Instead of manually writing hundreds of lines of CSS for every pseudo-class or media query, you populate a **property tree**. The system analyzes this file and performs all the routine work for you:
+- **Style Generation (SCSS)**: Creates BEM-style classes, variables, and themes.
+- **Interface Generation (Props)**: Forms public component properties for Vue/React.
+- **Synchronization**: Ensures that styles and the programmatic interface always correspond to each other.
 
-## Core Concepts
+## Core Concept
 
-- **Token**: A unit of style in the configuration object.
-- **Nesting**: The JSON structure determines the nesting of descendant CSS classes.
-- **Typing**: The JSON configuration is strictly divided by types: `var`, `state`, `media`, etc., which tells the generator exactly how the token will work in the output.
+1.  **Tokens**: JSON tree nodes representing specific CSS properties or nested objects.
+2.  **Types & Flags (_type, _var...)**: Service parameters defining the node processing logic (generating variables, states, or exporting to Props).
+3.  **Links**: The `{...}` system for inheriting values from other tokens or global design variables.
+4.  **Markers & Shortcuts**: Special prefixes (`~`, `group|`) and link placeholders (`?`, `??`) that accelerate the creation of complex configurations.

package/src/media/functional/ui/properties/about/about.ru.mdx

@@ -1,20 +1,21 @@
 import {Meta} from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/ru/# UI/properties/! О модуле'/>
+<Meta title='@dxtmisha/ru/# UI/properties/! О файле properties.json'/>
 
-# Properties
+# Конфигурация (properties.json)
 
-Модуль `Properties` служит для декларативного управления стилями дизайн-системы с помощью JSON-конфигураций. Разработчику компонентов больше не нужно вручную прописывать SCSS-код для состояний, медиа-запросов и переменных — вместо этого все дизайн-токены описываются в файле `properties.json`.
+Файл `properties.json` является декларативным манифестом вашего компонента. В нем вы описываете структуру, стили, состояния и параметры, которые затем автоматически преобразуются в готовый SCSS-код и типизированные TypeScript-интерфейсы (`props.ts`).
 
-## Для чего нужен этот файл?
+## Как работать с этим файлом?
 
-В каждой масштабируемой библиотеке UI-компонентов присутствует общая проблема управления отступами, цветами и состояниями (hover, focus, disabled). Создание файла `properties.json` позволяет:
-- Централизовать все токены в одном понятном месте рядом с компонентом.
-- Автоматически генерировать из него типизированные пропсы для Vue/React.
-- Получать готовые SCSS-классы, переменные и темы без дублирования кода.
+Вместо того чтобы вручную писать сотни строк CSS для каждого псевдокласса или медиа-запроса, вы наполняете **дерево свойств**. Система анализирует этот файл и выполняет всю рутинную работу:
+- **Генерация стилей (SCSS)**: Создает классы по методологии BEM, переменные и темы.
+- **Генерация интерфейса (Props)**: Формирует публичные свойства компонента для Vue/React.
+- **Синхронизация**: Гарантирует, что стили и программный интерфейс всегда соответствуют друг другу.
 
-## Основные концепции
+## Основная концепция
 
-- **Токен**: Единица стиля в объекте конфигурации.
-- **Вложенность**: Структура JSON определяет вложенность CSS классов-потомков.
-- **Типизация**: JSON-конфигурация строго разделена по типам: `var`, `state`, `media` и т.д., что подсказывает генератору, как именно будет работать токен на выходе.
+1.  **Токены (Tokens)**: Узлы дерева JSON, описывающие конкретные CSS-свойства или вложенные объекты.
+2.  **Типы и Флаги (_type, _var...)**: Служебные параметры, определяющие логику обработки узла (генерация переменной, состояния или экспорт в Props).
+3.  **Ссылки (Links)**: Система `{...}`, позволяющая заимствовать значения из других токенов или глобальных переменных дизайна.
+4.  **Маркеры и Шорткаты**: Специальные префиксы (`~`, `group|`) и подстановки (`?`, `??`), ускоряющие написание сложных конфигураций.

package/src/media/functional/ui/properties/about/about.vi.mdx

@@ -1,20 +1,21 @@
 import {Meta} from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/vi/# UI/properties/! Về module'/>
+<Meta title='@dxtmisha/vi/# UI/properties/! Về properties.json'/>
 
-# Properties
+# Cấu hình (properties.json)
 
-Module `Properties` phục vụ cho việc quản lý khai báo các style của hệ thống thiết kế thông qua cấu hình JSON. Nhờ đó, người phát triển component không còn phải code SCSS cho các trạng thái, media-query hay biến theo cách thủ công — thay vào đó, toàn bộ design-token được khai báo tại tệp `properties.json`.
+Tệp `properties.json` là bản tuyên ngôn khai báo cho thành phần của bạn. Trong đó, bạn mô tả cấu trúc, kiểu dáng, trạng thái và tham số, sau đó chúng sẽ tự động được chuyển đổi thành mã SCSS hoàn chỉnh và các giao diện TypeScript có kiểu dữ liệu (`props.ts`).
 
-## Tại sao cần có tệp này?
+## Làm thế nào để làm việc với tệp này?
 
-Trong bất kì thư viện UI component có quy mô nào, vấn đề phổ biến nhất là quản lý khoảng cách, màu sắc và trạng thái (hover, focus, disabled). Tệp cấu hình `properties.json` cho phép:
-- Quản lý tập trung mọi token một cách dễ hiểu nằm ngay cạnh component.
-- Tự động sinh ra props chặt chẽ cho Vue/React.
-- Lấy SCSS class, biến và theme dựng sẵn mà không cần lặp code.
+Thay vì viết hàng trăm dòng CSS thủ công cho mọi pseudo-class hoặc media query, bạn điền vào một **cây thuộc tính**. Hệ thống phân tích tệp này và thực hiện mọi công việc lặp đi lặp lại:
+- **Tạo kiểu dáng (SCSS)**: Tạo ra các lớp theo phương pháp BEM, các biến và chủ đề.
+- **Tạo giao diện (Props)**: Hình thành các thuộc tính thành phần công khai cho Vue/React.
+- **Đồng bộ hóa**: Đảm bảo rằng các kiểu dáng và giao diện lập trình luôn tương ứng với nhau.
 
-## Các khái niệm cơ bản
+## Khái niệm cốt lõi
 
-- **Token**: Đơn vị khai báo style trong cấu hình đối tượng.
-- **Tính lồng nhau**: Cấu trúc lồng của JSON sẽ ánh xạ vào các lớp CSS lồng nhau khi render.
-- **Phân loại**: Khai báo JSON chia thành nhiều loại: `var`, `state`, `media`, v.v... định hướng chính xác kết quả đầu ra.
+1.  **Token**: Các nút cấp độ JSON mô tả thuộc tính CSS cụ thể hoặc các đối tượng lồng nhau.
+2.  **Loại và Cờ (_type, _var...)**: Các tham số dịch vụ xác định logic xử lý nút (tạo biến, trạng thái hoặc xuất ra Props).
+3.  **Liên kết (Links)**: Hệ thống `{...}` cho phép kế thừa giá trị từ các token khác hoặc các biến thiết kế toàn cục.
+4.  **Dấu hiệu và Phím tắt**: Các tiền tố đặc biệt (`~`, `group|`) và các trình giữ chỗ liên kết (`?`, `??`) giúp tăng tốc độ viết các cấu hình phức tạp.

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

@@ -1,78 +1,108 @@
 import {Meta} from '@storybook/addon-docs/blocks'
 
-<Meta title='@dxtmisha/en/# UI/properties/Quick start'/>
+<Meta title='@dxtmisha/en/# UI/properties/! Quick start'/>
 
 # Quick Start
 
-This guide covers the basics of onboarding your UI components onto the properties generation pipeline via `properties.json`.
+This guide helps you quickly master working with the `properties.json` file using a typical UI component as an example. The file serves as the **single source of truth** — both styles (SCSS) and the programmatic interface (TypeScript Props) are generated from it.
 
-## 1. Setting Up Base Styles
+## 1. Base Properties and Tokens
 
-The simplest configuration pattern maps flat JSON keys directly to native CSS attributes. Let's declare standard background and padding values:
+Instead of fixed values (HEX, px), always use the design token system `{sys...}`. This ensures theme support and consistency.
 
 ```json
 {
-  "background-color": "#cccccc",
-  "padding": "12px 24px"
+  "padding": "{sys.spacing.md}",
+  "background-color": "{sys.palette.surface}",
+  "border-radius": "{sys.rounded.md}"
 }
 ```
 
-During compilation, the pipeline processes this directly into functional SCSS layout classes binding to your setup namespace automatically:
+**Result (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. Emitting CSS Variables
+## 2. States
 
-Whenever an attribute must be dynamically manipulatable client-side (e.g. for custom scripting or interactive theming modes), utilize an object declaration bearing the `_var: true` flag.
+Use reserved keys to describe interactivity (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"
   }
 }
 ```
 
-Result pipeline mapping:
+**Result (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. Pseudo-classes and Variations
+## 3. Modifiers (Marker `~`)
 
-The generator inherently orchestrates logic-grouped structures into valid CSS pseudo-classes or exported modifier variants natively:
+To create a variation of a component (e.g., `primary` or `secondary`), use the `~` prefix. These keys are automatically transformed into **Props** in Vue/React and BEM modifiers in CSS.
 
 ```json
 {
-  "hover": {
-    "background-color": "#aaaaaa"
-  },
-  "~active": {
-    "background-color": "#555555"
+  "~primary": {
+    "color": "{sys.palette.onPrimary}",
+    "background-color": "{sys.palette.primary}",
+    "_default": true
   }
 }
 ```
 
-Compiled bindings logic:
+**Result (SCSS):**
 ```scss
 .component {
-  &:hover {
-    background-color: #aaaaaa;
+  &--primary {
+    color: var(--sys-palette-onPrimary);
+    background-color: var(--sys-palette-primary);
   }
-  
-  /* BEM modifier mapped via TypeScript Props */
-  &--active {
-    background-color: #555555;
+}
+```
+
+**Result (TypeScript Props):**
+```typescript
+type PropsToken = {
+  primary?: boolean // Generated automatically
+}
+```
+
+## 4. Custom Variables (`_var`)
+
+If you need a property to be available as a CSS variable for external control or use in scripts, add the `_var: true` flag.
+
+```json
+{
+  "height": {
+    "value": "48px",
+    "_var": true
   }
 }
 ```
 
-> **Note:** To leverage deep referencing design tokens (`{sys...}`) and systematic TypeScript props interfaces exports, review the full **Structure description** documentation.
+**Result (SCSS):**
+```scss
+.component {
+  --component-height: 48px;
+  height: var(--component-height);
+}
+```
+