@dxtmisha/wiki 0.39.2 → 0.39.3

package/src/media/functional/ui/properties/flag-var/flag-var.vi.mdx

@@ -0,0 +1,27 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/vi/# UI/properties/flags/Biến (var)'/>
+
+# Biến (var)
+
+Cờ `_var: true` buộc trình biên dịch tạo một biến CSS riêng cho nút đó, ngay cả khi nó đã là một thuộc tính tiêu chuẩn. Điều này hữu ích cho việc ghi đè động qua JS hoặc hỗ trợ kề thừa.
+
+**Cấu hình đầu vào (`properties.json`):**
+```json
+{
+  "button": {
+    "padding": {
+      "value": "16px",
+      "_var": true
+    }
+  }
+}
+```
+
+**Kết quả (SCSS):**
+```scss
+.button {
+  --button-padding: 16px;
+  padding: var(--button-padding);
+}
+```

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

@@ -0,0 +1,78 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<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`.
+
+## 1. Setting Up Base Styles
+
+The simplest configuration pattern maps flat JSON keys directly to native CSS attributes. Let's declare standard background and padding values:
+
+```json
+{
+  "background-color": "#cccccc",
+  "padding": "12px 24px"
+}
+```
+
+During compilation, the pipeline processes this directly into functional SCSS layout classes binding to your setup namespace automatically:
+```scss
+.component {
+  background-color: #cccccc;
+  padding: 12px 24px;
+}
+```
+
+## 2. Emitting CSS Variables
+
+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.
+
+```json
+{
+  "border-radius": {
+    "_var": true,
+    "value": "8px"
+  }
+}
+```
+
+Result pipeline mapping:
+```scss
+.component {
+  --component-border-radius: 8px;
+  border-radius: var(--component-border-radius);
+}
+```
+
+## 3. Pseudo-classes and Variations
+
+The generator inherently orchestrates logic-grouped structures into valid CSS pseudo-classes or exported modifier variants natively:
+
+```json
+{
+  "hover": {
+    "background-color": "#aaaaaa"
+  },
+  "~active": {
+    "background-color": "#555555"
+  }
+}
+```
+
+Compiled bindings logic:
+```scss
+.component {
+  &:hover {
+    background-color: #aaaaaa;
+  }
+  
+  /* BEM modifier mapped via TypeScript Props */
+  &--active {
+    background-color: #555555;
+  }
+}
+```
+
+> **Note:** To leverage deep referencing design tokens (`{sys...}`) and systematic TypeScript props interfaces exports, review the full **Structure description** documentation.

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

@@ -0,0 +1,78 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/# UI/properties/Быстрый старт'/>
+
+# Быстрый старт
+
+Данное руководство демонстрирует основы внедрения кодогенерации для вашего UI-компонента с помощью `properties.json`.
+
+## 1. Базовые стили
+
+Простейшая конфигурация строится на прямом соответствии ключей физическим CSS-свойствам. Добавим базовый фон и отступы:
+
+```json
+{
+  "background-color": "#cccccc",
+  "padding": "12px 24px"
+}
+```
+
+Генератор свойств автоматически сформирует следующий SCSS-класс (название класса выводится из базовых настроек вашей дизайн-системы):
+```scss
+.component {
+  background-color: #cccccc;
+  padding: 12px 24px;
+}
+```
+
+## 2. Генерация CSS переменных
+
+Если вам нужно, чтобы свойство выводилось как динамическая CSS-переменная (например, для использования в скриптах или темах), используйте конфигурационный объект с флагом `_var: true` или `_type: "var"`.
+
+```json
+{
+  "border-radius": {
+    "_var": true,
+    "value": "8px"
+  }
+}
+```
+
+Результат:
+```scss
+.component {
+  --component-border-radius: 8px;
+  border-radius: var(--component-border-radius);
+}
+```
+
+## 3. Состояния и модификаторы
+
+Генератор автоматически транслирует вложенные древовидные структуры в псевдоклассы (состояния) и БЭМ-модификаторы:
+
+```json
+{
+  "hover": {
+    "background-color": "#aaaaaa"
+  },
+  "~active": {
+    "background-color": "#555555"
+  }
+}
+```
+
+Результат:
+```scss
+.component {
+  &:hover {
+    background-color: #aaaaaa;
+  }
+  
+  /* БЭМ модификатор для Vue Props */
+  &--active {
+    background-color: #555555;
+  }
+}
+```
+
+> **Важно:** Для более сложной конфигурации, работы с дизайн-токенами `{sys...}` и автоматической типизации интерфейса, изучите раздел **Описание структуры**.

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

@@ -0,0 +1,78 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<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`.
+
+## 1. Thiết lập CSS cơ bản
+
+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):
+
+```json
+{
+  "background-color": "#cccccc",
+  "padding": "12px 24px"
+}
+```
+
+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):
+```scss
+.component {
+  background-color: #cccccc;
+  padding: 12px 24px;
+}
+```
+
+## 2. Khai báo biến CSS Variables Động
+
+Để đả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`.
+
+```json
+{
+  "border-radius": {
+    "_var": true,
+    "value": "8px"
+  }
+}
+```
+
+Kết quả gen-code block SCSS:
+```scss
+.component {
+  --component-border-radius: 8px;
+  border-radius: var(--component-border-radius);
+}
+```
+
+## 3. Tổ hợp Trạng thái và Modifiers BEM
+
+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:
+
+```json
+{
+  "hover": {
+    "background-color": "#aaaaaa"
+  },
+  "~active": {
+    "background-color": "#555555"
+  }
+}
+```
+
+Thành phẩm sau quy trình module framework nhận được:
+```scss
+.component {
+  &:hover {
+    background-color: #aaaaaa;
+  }
+  
+  /* Chuỗi BEM modifier tự động chuẩn bị map prop TypeScript */
+  &--active {
+    background-color: #555555;
+  }
+}
+```
+
+> **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**.

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

@@ -0,0 +1,155 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/en/# UI/properties/# Structure'/>
+
+# Structure
+
+The `properties.json` configuration acts completely as a tree structure. Object keys on every depth boundary act as explicit names (selectors), and bottom leaf-nodes act as actual style setups (known as `PropertyItem`). Any standard CSS property explicitly defined as a key naturally generates valid CSS mapping formatting. 
+
+The following structure demonstrates the definition of base styles, state modifiers (`hover`, `disabled`), and stylistic variations that compile into Vue Props.
+
+```json
+{
+  "padding": "var(--sys-height) * {sys.spacing.adaptive.md}",
+  
+  "hover": {
+    "gradient-opacity": "{sys.opacity.hover}"
+  },
+
+  "disabled": {
+    "color": "{sys.palette.onSurface}",
+    "color-opacity": "{sys.opacity.surface.disabled}"
+  },
+
+  "~primary": {
+    "color": "{sys.palette.onPrimary}",
+    "palette-background": "{sys.palette.primary}",
+    "active": {
+      "box-shadow": "{sys.shadow.lg}"
+    },
+    "_category": "style",
+    "_default": true
+  },
+
+  "~size": {
+    "sm": {
+      "height": "{ref.spacing.10}"
+    },
+    "md": {
+      "height": "{ref.spacing.12}"
+    },
+    "_default": "md"
+  }
+}
+```
+
+The properties generator processes the JSON schema via the following compilation rules:
+1. Physical style keys (e.g., `padding`) are inherently generated inside the `.component` CSS layout block.
+2. System token linkages wrapped in `{...}` are correctly resolved into their designated design system CSS variables.
+3. Property variations mapped with the `~` prefix are concurrently compiled into structural CSS modifiers (e.g., `--primary`) and exported into the component's TypeScript interface.
+
+Generated SCSS compilation:
+```scss
+.component {
+  padding: calc(var(--sys-height) * var(--sys-spacing-adaptive-md));
+
+  /* Pseudo-classes states */
+  &:hover {
+    --component-gradient-opacity: var(--sys-opacity-hover);
+  }
+  &:disabled {
+    color: var(--sys-palette-onSurface);
+    --component-color-opacity: var(--sys-opacity-surface-disabled);
+  }
+
+  /* Modification category "style": --primary */
+  &--primary {
+    color: var(--sys-palette-onPrimary);
+    background-color: var(--sys-palette-primary);
+    
+    &:active {
+      box-shadow: var(--sys-shadow-lg);
+    }
+  }
+
+  /* Modifiers groups "size" */
+  &--size-sm { height: var(--ref-spacing-10); }
+  &--size-md { height: var(--ref-spacing-12); }
+}
+```
+
+Generated Vue Props interface (`props.ts`):
+```typescript
+type PropsToken = {
+  // :type [!] System label / Системная метка
+  primary?: boolean
+  size?: 'sm' | 'md'
+  // :type [!] System label / Системная метка
+}
+
+export const defaults: object = {
+  // :default [!] System label / Системная метка
+  primary: true,
+  size: 'md'
+  // :default [!] System label / Системная метка
+}
+```
+
+Generated Vue class binding logic:
+```typescript
+const classesToken = computed<ConstrClasses>(() => ({
+  main: {
+    // :classes-values [!] System label / Системная метка
+    'component': true,
+    'component--primary': props.primary,
+    [`component--size--${props.size}`]: inArray(propsValues.size, props.size)
+    // :classes-values [!] System label / Системная метка
+  }
+}))
+```
+
+## Key Hierarchy
+
+Normally the depth pattern follows:
+1. Root Domain node — `[Design / Global scope Name]` (e.g. `ui`, `d1`)
+2. Element node — `[Component Name]` (e.g. `component`)
+3. Logic node — `[Styles, sub-components, properties attributes]` (e.g. `background`, `size`, `hover`, `--padding`)
+
+## Inter-Links Mapping
+
+Values wrapped in curly braces (e.g., `"{sys.palette.primary}"` or `"{ref.spacing.10}"`) allow you to dynamically reference design system tokens. During compilation, they are substituted with their actual CSS variables or mapped absolute values automatically.
+
+## Service flags
+
+All configuration keys managing the generator processes start with a bottom underscore `_`.
+
+### Fundamental Identifiers
+
+- `_type: string` — Maps the output generator rendering component rule (`var`, `state`, `subclass`, `media`).
+- `_category: string` — Provides metadata classification tagging for sortings explicitly.
+
+### Behaviors modifications
+
+- `_var: boolean` — Signals generator building mapping local CSS variable format explicitly for node (`--name: value`).
+- `_state: boolean` — Tags current processing node matching internal `state` processing rendering setup layout block configuration.
+- `_subclass: boolean` — Sets local component identifying subclass nested properties.
+- `_prop: boolean` — Includes the node processing result towards `props.ts` generation exporting value via Vue/React.
+- `_theme: string` — Anchors processing layout styles to specified color theme processing dynamically.
+
+### Parsing and parameters
+
+- `_rename: string` — Overrides output strings variable representation. (Key `backgroundItem` with `_rename: "bg"` outputs `.component__bg`).
+- `_replace: string` — Allows replacing the pattern via internal RegEx match configurations.
+- `_fullName: string` — Ignores standard tree names scoping mapping explicit structure strings exactly.
+- `_fullValue: string` — Outputs precise variable processing strings avoiding numbers/px suffix parsing parameters.
+- `_default: any` — Outputs parameter configurations applying exact properties as fallback mechanism natively values outputs logic setups.
+
+### Structure Architecture Configs
+
+- `_important: boolean` — Extends parameter applying matching output rendering value logic via `!important`.
+- `_modification: boolean` — Modifies structure explicitly rendering variations handling element structures specifically.
+- `_drag: string` — Points pipeline pulling sub-tree data replacing into different configurations path branches automatically logic processing setups configurations.
+- `_dragSetting: boolean` — Pushes internal nested processing setups propagating settings internally towards leaf nodes.
+- `_settingClone: boolean` — Clones the current configuration settings propagating them into nested levels.
+- `_style: boolean` — Outputs local structural CSS layouts variables explicitly inline styles layouts structures parameters correctly.
+- `_remove: boolean` — Filters out current processing element structure completely erasing node output mapping rendering format.

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

@@ -0,0 +1,155 @@
+import {Meta} from '@storybook/addon-docs/blocks'
+
+<Meta title='@dxtmisha/ru/# UI/properties/# Структура'/>
+
+# Структура
+
+Файл `properties.json` имеет древовидную структуру. Ключи на каждом уровне могут выступать в качестве имен (селекторов) или служебных настроек. Само значение (листовой узел) представляет собой конфигурационный объект `PropertyItem`. Любое стандартное CSS свойство, указанное как ключ, будет преобразовано в правильный CSS синтаксис.
+
+Ниже приведена базовая структура, демонстрирующая определение стилей, модификаторов состояний (`hover`, `disabled`) и вариаций, которые транслируются во Vue Props.
+
+```json
+{
+  "padding": "var(--sys-height) * {sys.spacing.adaptive.md}",
+  
+  "hover": {
+    "gradient-opacity": "{sys.opacity.hover}"
+  },
+
+  "disabled": {
+    "color": "{sys.palette.onSurface}",
+    "color-opacity": "{sys.opacity.surface.disabled}"
+  },
+
+  "~primary": {
+    "color": "{sys.palette.onPrimary}",
+    "palette-background": "{sys.palette.primary}",
+    "active": {
+      "box-shadow": "{sys.shadow.lg}"
+    },
+    "_category": "style",
+    "_default": true
+  },
+
+  "~size": {
+    "sm": {
+      "height": "{ref.spacing.10}"
+    },
+    "md": {
+      "height": "{ref.spacing.12}"
+    },
+    "_default": "md"
+  }
+}
+```
+
+Генератор свойств обрабатывает данную структуру по следующим правилам компиляции:
+1. Ключи физических свойств (например, `padding`) генерируются как свойства CSS-класса `.component`.
+2. Ссылки на дизайн-токены в формате `{...}` разрешаются в соответствующие CSS-переменные дизайн-системы.
+3. Вариации свойств, отмеченные префиксом `~`, преобразуются в CSS-модификаторы (например, `--primary`) и транслируются в интерфейс компонента (props TypeScript).
+
+Сгенерированный SCSS-код:
+```scss
+.component {
+  padding: calc(var(--sys-height) * var(--sys-spacing-adaptive-md));
+
+  /* Псевдоклассы состояний */
+  &:hover {
+    --component-gradient-opacity: var(--sys-opacity-hover);
+  }
+  &:disabled {
+    color: var(--sys-palette-onSurface);
+    --component-color-opacity: var(--sys-opacity-surface-disabled);
+  }
+
+  /* Модификатор категории "style": --primary */
+  &--primary {
+    color: var(--sys-palette-onPrimary);
+    background-color: var(--sys-palette-primary);
+    
+    &:active {
+      box-shadow: var(--sys-shadow-lg);
+    }
+  }
+
+  /* Модификаторы группы "size" */
+  &--size-sm { height: var(--ref-spacing-10); }
+  &--size-md { height: var(--ref-spacing-12); }
+}
+```
+
+Сгенерированный интерфейс Vue Props (`props.ts`):
+```typescript
+type PropsToken = {
+  // :type [!] System label / Системная метка
+  primary?: boolean
+  size?: 'sm' | 'md'
+  // :type [!] System label / Системная метка
+}
+
+export const defaults: object = {
+  // :default [!] System label / Системная метка
+  primary: true,
+  size: 'md'
+  // :default [!] System label / Системная метка
+}
+```
+
+Сгенерированная логика привязки классов:
+```typescript
+const classesToken = computed<ConstrClasses>(() => ({
+  main: {
+    // :classes-values [!] System label / Системная метка
+    'component': true,
+    'component--primary': props.primary,
+    [`component--size--${props.size}`]: inArray(propsValues.size, props.size)
+    // :classes-values [!] System label / Системная метка
+  }
+}))
+```
+
+## Иерархия ключей
+
+Стандартный паттерн иерархии ключей:
+1. Корневой узел — `[Название группы или дизайна]` (например, `ui`, `d1`)
+2. Подузел — `[Название компонента]` (например, `component`)
+3. Элементы — `[Физические CSS-свойства или вложенные классы]` (например, `background`, `size`, `hover`, `--padding`)
+
+## Использование ссылок
+
+Значения, обёрнутые в фигурные скобки (например, `"{sys.palette.primary}"` или `"{ref.spacing.10}"`), позволяют динамически ссылаться на дизайн-токены системы. При сборке генератор автоматически заменяет их на реальные CSS-переменные или абсолютные значения.
+
+## Служебные флаги
+
+Специальные ключи конфигурации (флаги) используются для управления генерацией стилей. Все они начинаются со знака подчеркивания `_`.
+
+### Основные идентификаторы
+
+- `_type: string` — Определяет тип компонента или правила генерации (`var`, `state`, `subclass`, `media` и т.д.).
+- `_category: string` — Дополнительный определитель категории для сортировки или фильтрации.
+
+### Модификаторы поведения
+
+- `_var: boolean` — Заставляет генератор дополнительно создать CSS переменную `--name: value` для узла.
+- `_state: boolean` — Помечает текущий узел как состояние (аналог `_type: "state"`).
+- `_subclass: boolean` — Помечает текущий узел как подкласс.
+- `_prop: boolean` — Указывает, что это значение следует экспортировать как Vue/React Prop (реактивное свойство) в `props.ts`.
+- `_theme: string` — Привязывает текущие стили к конкретной теме.
+
+### Инструменты значений
+
+- `_rename: string` — Переопределяет название свойства или класса в конечном коде. (Например, ключ `backgroundItem`, но с `_rename: "bg"` класс выйдет `.component__bg`).
+- `_replace: string` — Позволяет полностью заменить финальное имя или структуру через шаблонное регулярное выражение.
+- `_fullName: string` — Жёстко задаёт полное название для CSS-класса/переменной, игнорируя древовидный контекст.
+- `_fullValue: string` — Выводит значение "как есть", игнорируя парсинг чисел и пикселей.
+- `_default: any` — Разрешает назначить базовое значение (fallback) для компонента.
+
+### Управление структурой
+
+- `_important: boolean` — Добавляет спецификатор `!important` к правилу.
+- `_modification: boolean` — Используется для обозначения свойств-модификаторов.
+- `_drag: string` — Перетаскивает (внедряет) этот узел в другое место дерева во время сборки. Полезно для алиасов.
+- `_dragSetting: boolean` — Включает перенос (наследование) внутренних настроек узла в его дочерние элементы.
+- `_settingClone: boolean` — Клонирует текущие настройки конфигурации и распространяет их на вложенные уровни.
+- `_style: boolean` — Принудительно генерирует инлайн-стиль вместо класса.
+- `_remove: boolean` — Исключает данный узел из финальной генерации в SCSS/JS файлы.