dxd-style-code 0.1.11 → 0.1.12

package/src/components/atoms/DX/DX.vue

@@ -0,0 +1,80 @@
+<template>
+  <component
+    :is="componentTag"
+    :class="computedClass"
+    data-component="DX"
+    v-bind="componentAttrs"
+  >
+    <slot />
+  </component>
+</template>
+
+<script setup>
+import { computed, useAttrs } from "vue";
+
+const props = defineProps({
+  /** HTML тег элемента (div, span, button, a, nav, header, section, article и т.д.) */
+  as: {
+    type: String,
+    default: "div",
+  },
+  /** Дополнительные CSS классы */
+  class: {
+    type: [String, Array, Object],
+    default: null,
+  },
+});
+
+const attrs = useAttrs();
+
+/**
+ * Атрибуты для передачи на компонент (исключая class, который обрабатывается отдельно)
+ * 
+ * @description
+ * В Vue 3 с <script setup>, props определенные через defineProps автоматически
+ * не попадают в $attrs. Исключаем только class, так как он обрабатывается через computedClass.
+ */
+const componentAttrs = computed(() => {
+  const { class: _, ...rest } = attrs;
+  return rest;
+});
+
+/**
+ * Определяет HTML тег для рендеринга
+ * 
+ * @description
+ * Возвращает HTML тег из prop `as` или дефолтный `div`.
+ * 
+ * @returns {string} HTML тег для рендеринга
+ */
+const componentTag = computed(() => {
+  return props.as || "div";
+});
+
+/**
+ * Вычисляет классы для компонента
+ * 
+ * @description
+ * Объединяет prop class с любыми классами из $attrs.
+ * 
+ * @returns {string|Array|Object} Классы для применения к элементу
+ */
+const computedClass = computed(() => {
+  const classes = [];
+  
+  // Добавляем класс из prop class
+  if (props.class) {
+    classes.push(props.class);
+  }
+  
+  // Добавляем класс из $attrs.class если есть
+  if (attrs.class) {
+    classes.push(attrs.class);
+  }
+  
+  // Возвращаем массив если есть несколько классов, иначе одно значение
+  return classes.length > 1 ? classes : classes[0] || null;
+});
+
+</script>
+

package/src/components/atoms/DX/index.js

@@ -0,0 +1,2 @@
+export { default } from './DX.vue';
+

package/src/components/atoms/DXAvatar/DXAvatar.stories.js

@@ -10,12 +10,11 @@ import {
 export default {
   title: 'Atoms/DXAvatar',
   component: DXAvatar,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'category:data-display'],
   parameters: {
     docs: {
       description: {
         component: `
-# DXAvatar
 
 Компонент аватара пользователя с поддержкой изображений, инициалов и иконок.
 

package/src/components/atoms/DXBackdrop/DXBackdrop.stories.js

@@ -5,7 +5,83 @@ import { ref, computed } from 'vue';
 export default {
   title: 'Atoms/DXBackdrop',
   component: DXBackdrop,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'category:overlay'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+# DXBackdrop
+
+Компонент фона (backdrop) для модальных окон и overlay элементов с поддержкой размытия и блокировки скролла.
+
+## Назначение
+
+DXBackdrop предоставляет стандартизированный фон для модальных окон, сайдбаров и других overlay элементов.
+Компонент поддерживает различные уровни размытия, настраиваемый цвет фона, блокировку скролла
+и возможность закрытия по клику.
+
+## Архитектура
+
+### Использует
+- \`Teleport\` - для рендеринга в body
+- \`Transition\` - для анимации появления/исчезновения
+
+### Используется в
+- \`DXModal\` - фон для модальных окон
+- \`DXSidebar\` - фон для боковых панелей (в overlay режиме)
+- \`DXDropdown\` - фон для выпадающих меню
+- Любые overlay компоненты
+
+## Внутренняя логика
+
+### Размытие
+Поддерживает 5 уровней размытия:
+- **none** - без размытия
+- **sm** - слабое размытие (по умолчанию)
+- **md** - среднее размытие
+- **lg** - сильное размытие
+- **xl** - очень сильное размытие
+
+### Цвет фона
+Настраивается через \`backgroundColor\` prop:
+- По умолчанию: \`bg-slate-900/40\` (темный полупрозрачный)
+- Можно использовать любые Tailwind классы: \`bg-black/50\`, \`bg-slate-900/60\` и т.д.
+- Можно использовать CSS значения: \`rgb(0, 0, 0, 0.5)\`
+
+### Z-index
+Поддерживает настраиваемый z-index:
+- **0, 10, 20, 30, 40, 50, auto**
+- По умолчанию: \`50\` (для модальных окон)
+
+### Блокировка скролла
+При \`lockScroll={true}\` (по умолчанию):
+- Добавляет \`overflow-hidden\` к body при показе
+- Убирает при скрытии
+- Автоматически очищается при размонтировании компонента
+
+### Закрытие
+При \`dismissible={true}\` (по умолчанию):
+- Клик на backdrop эмитит событие \`close\`
+- Курсор меняется на pointer для визуальной индикации
+
+## Особенности
+
+### Teleport
+Компонент автоматически рендерится в \`body\` через Vue Teleport для правильного z-index стека.
+
+### Анимация
+Использует fade transition для плавного появления/исчезновения.
+
+### События
+- \`@click\` - эмитится при клике на backdrop
+- \`@close\` - эмитится при закрытии (если \`dismissible={true}\`)
+
+### Слоты
+Поддерживает default slot для размещения контента поверх backdrop (например, модальное окно).
+        `,
+      },
+    },
+  },
   argTypes: {
     blur: {
       control: 'select',

package/src/components/atoms/DXBadge/DXBadge.stories.js

@@ -15,7 +15,89 @@ import {
 export default {
   title: 'Atoms/DXBadge',
   component: DXBadge,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'category:data-display'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+# DXBadge
+
+Компонент бейджа для отображения статусов, меток и индикаторов с поддержкой иконок.
+
+## Назначение
+
+DXBadge предоставляет компактный способ отображения статусов, меток, счетчиков и других индикаторов.
+Компонент поддерживает различные цветовые варианты, размеры и возможность добавления иконок слева и справа.
+
+## Архитектура
+
+### Использует
+- \`DXIcon\` - для отображения иконок слева и справа
+- \`useSize\` composable - для унификации размеров (sm, md)
+- \`useVariantBadge\` composable - для вариантов оформления
+- \`useClassComposition\` composable - для объединения CSS классов
+
+### Используется в
+- Статусы элементов (активен, неактивен, в ожидании)
+- Счетчики уведомлений
+- Метки категорий и тегов
+- Индикаторы состояния
+- Бейджи в таблицах и списках
+- Элементы меню с счетчиками
+
+## Внутренняя логика
+
+### Варианты оформления
+- **slate** (по умолчанию): Нейтральный серый цвет
+- **success**: Зеленый цвет для успешных состояний
+- **warning**: Желтый цвет для предупреждений
+- **danger**: Красный цвет для ошибок и критических состояний
+- **info**: Синий цвет для информационных меток
+
+### Размеры
+Поддерживает два размера:
+- **sm** (по умолчанию) - маленький размер
+- **md** - средний размер
+
+### Иконки
+- **iconLeft** - иконка слева от текста (Heroicon компонент)
+- **iconRight** - иконка справа от текста (Heroicon компонент)
+- Размер иконок автоматически адаптируется к размеру бейджа (xs)
+
+## Особенности
+
+### Форма
+Все бейджи имеют форму \`rounded-full\` (полностью скругленные углы) для единообразного внешнего вида.
+
+### Структура
+Бейдж состоит из:
+1. Иконка слева (опционально)
+2. Текст (через default slot)
+3. Иконка справа (опционально)
+
+### Использование
+Бейджи обычно используются для:
+- Статусов: "Активен", "Неактивен", "В ожидании"
+- Счетчиков: количество уведомлений, элементов
+- Меток: категории, теги, типы
+- Индикаторов: "Новое", "Горячее", "Популярное"
+
+### Комбинации
+Можно комбинировать:
+- Только текст
+- Текст + иконка слева
+- Текст + иконка справа
+- Текст + обе иконки
+- Только иконки (без текста)
+
+### Стилизация
+- Все варианты имеют рамку (\`border\`)
+- Фон и текст автоматически подбираются для каждого варианта
+- Шрифт: \`font-semibold\` для лучшей читаемости
+        `,
+      },
+    },
+  },
   argTypes: {
     variant: {
       control: 'select',

package/src/components/atoms/DXBlockquote/DXBlockquote.stories.js

@@ -3,7 +3,73 @@ import DXBlockquote from './DXBlockquote.vue';
 export default {
   title: 'Atoms/DXBlockquote',
   component: DXBlockquote,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'category:typography'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+# DXBlockquote
+
+Компонент для отображения блочных цитат с поддержкой различных вариантов оформления и источника.
+
+## Назначение
+
+DXBlockquote предоставляет стандартизированный способ отображения блочных цитат в статьях,
+блогах и документации. Компонент поддерживает различные варианты визуального оформления
+и возможность указания источника цитаты.
+
+## Архитектура
+
+### Использует
+- Семантический HTML тег \`<blockquote>\` - для блочных цитат
+- Семантический HTML тег \`<cite>\` - для источника цитаты
+
+### Используется в
+- Статьи и блоги
+- Документация
+- Отзывы и рекомендации
+- Любые места, требующие отображения цитат
+
+## Внутренняя логика
+
+### Варианты оформления
+- **default**: Обычная цитата без рамки, только курсив
+- **bordered** (по умолчанию): Цитата с левой рамкой
+- **highlighted**: Цитата с фоном и рамкой для выделения
+
+### Размеры
+Поддерживает 3 размера текста:
+- **sm** - маленький текст
+- **md** - средний текст (по умолчанию)
+- **lg** - большой текст
+
+### Источник цитаты
+Можно указать источник через:
+- \`cite\` prop - текст источника
+- Слот \`cite\` - кастомный источник
+
+Источник отображается в footer с дефисом и курсивом.
+
+## Особенности
+
+### Семантика
+Использует семантически правильные HTML теги:
+- \`<blockquote>\` для цитаты
+- \`<cite>\` для источника
+
+Это важно для:
+- SEO (поисковые системы понимают цитаты)
+- Доступности (скринридеры правильно обрабатывают цитаты)
+- Семантической правильности HTML
+
+### Визуальное оформление
+- **default**: Только курсив, без дополнительного оформления
+- **bordered**: Левая рамка 4px, padding слева, курсив
+- **highlighted**: Фон (bg-slate-50), левая рамка, padding, скругление справа
+        `,
+      },
+    },
+  },
   argTypes: {
     variant: { control: { type: 'select' }, options: ['default', 'bordered', 'highlighted'] },
   },

package/src/components/atoms/DXBox/DXBox.stories.js

@@ -3,7 +3,7 @@ import DXBox from './DXBox.vue';
 export default {
   title: 'Atoms/DXBox',
   component: DXBox,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'category:layout'],
   parameters: {
     docs: {
       description: {

package/src/components/atoms/DXBox/DXBox.vue

@@ -1,5 +1,5 @@
 <template>
-  <component :is="tag" :class="boxClasses" data-component="DXBox">
+  <component :is="tag" :class="boxClasses" data-component="DXBox" :data-position="position" :data-z-index="zIndex">
     <slot />
   </component>
 </template>
@@ -32,6 +32,12 @@ const props = defineProps({
   shadow: { type: String, default: "" },
   /** Рамка */
   border: { type: Boolean, default: false },
+  /** Позиционирование: static | relative | absolute | fixed | sticky */
+  position: { type: String, default: null },
+  /** z-index: 0 | 10 | 20 | 30 | 40 | 50 | auto */
+  zIndex: { type: String, default: null },
+  /** Inset (top-0 right-0 bottom-0 left-0) */
+  inset: { type: Boolean, default: false },
 });
 
 /**
@@ -173,11 +179,69 @@ const shadowClass = computed(() => {
   return shadowClasses[props.shadow] || `shadow-${props.shadow}`;
 });
 
+/**
+ * Классы позиционирования
+ * 
+ * @description
+ * Определяет CSS position для box компонента.
+ * 
+ * @returns {string|null} Tailwind CSS класс для позиционирования или null
+ */
+const positionClass = computed(() => {
+  if (!props.position) return null;
+  
+  const positionClasses = {
+    static: "static",
+    relative: "relative",
+    absolute: "absolute",
+    fixed: "fixed",
+    sticky: "sticky",
+  };
+  
+  return positionClasses[props.position] || null;
+});
+
+/**
+ * Классы z-index
+ * 
+ * @description
+ * Определяет z-index для box компонента.
+ * 
+ * @returns {string|null} Tailwind CSS класс для z-index или null
+ */
+const zIndexClass = computed(() => {
+  if (!props.zIndex) return null;
+  
+  const zIndexClasses = {
+    "0": "z-0",
+    "10": "z-10",
+    "20": "z-20",
+    "30": "z-30",
+    "40": "z-40",
+    "50": "z-50",
+    auto: "z-auto",
+  };
+  
+  return zIndexClasses[props.zIndex] || null;
+});
+
+/**
+ * Класс inset
+ * 
+ * @description
+ * Применяет inset-0 (top-0 right-0 bottom-0 left-0) для абсолютного/фиксированного позиционирования.
+ * 
+ * @returns {string|null} Tailwind CSS класс для inset или null
+ */
+const insetClass = computed(() => {
+  return props.inset ? "inset-0" : null;
+});
+
 /**
  * Все классы для box компонента
  * 
  * @description
- * Объединяет все классы стилизации (padding, margin, rounded, bg, shadow, border)
+ * Объединяет все классы стилизации (padding, margin, rounded, bg, shadow, border, position, zIndex, inset)
  * с использованием useClassComposition для единообразного подхода.
  * 
  * @returns {Array} Массив классов для применения к элементу
@@ -189,6 +253,9 @@ const boxClasses = computed(() =>
     roundedClass.value,
     bgClass.value,
     shadowClass.value,
+    positionClass.value,
+    zIndexClass.value,
+    insetClass.value,
     {
       "border border-slate-200": props.border,
     }

package/src/components/atoms/DXButton/DXButton.stories.js

@@ -5,7 +5,100 @@ import { PlusIcon, TrashIcon, PencilIcon, HeartIcon } from '@heroicons/vue/24/ou
 export default {
   title: 'Atoms/DXButton',
   component: DXButton,
-  tags: ['autodocs'],
+  tags: ['autodocs', 'category:form'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+# DXButton
+
+Универсальный компонент кнопки с поддержкой различных вариантов оформления, размеров и режимов использования.
+
+## Назначение
+
+DXButton предоставляет стандартизированный способ создания кнопок в приложении. Компонент поддерживает
+множество вариантов оформления, размеров, может работать как обычная кнопка, ссылка или router-link,
+а также автоматически адаптируется при использовании внутри DXButtonGroup.
+
+## Архитектура
+
+### Использует
+- \`useSize\` composable - для унификации размеров (xs, sm, md, lg, xl)
+- \`useVariantButton\` composable - для вариантов оформления
+- \`useClassComposition\` composable - для объединения CSS классов
+- \`provide/inject\` - для интеграции с DXButtonGroup
+
+### Используется в
+- \`DXButtonGroup\` - группы кнопок для выбора значений
+- \`DXPagination\` - кнопки навигации по страницам
+- \`DXModal\` - кнопки действий в модальных окнах
+- \`DXAlert\` - кнопки действий в уведомлениях
+- \`DXFormControl\` - кнопки в формах
+- Любые места, где требуется интерактивная кнопка
+
+## Внутренняя логика
+
+### Динамический рендеринг
+Компонент использует \`<component :is="componentTag">\` для выбора HTML тега:
+- Если указан \`to\` prop → рендерится как \`router-link\` (Vue Router)
+- Если указан \`href\` prop → рендерится как \`<a>\` (обычная ссылка)
+- По умолчанию → рендерится как \`<button>\`
+
+### Интеграция с DXButtonGroup
+При использовании внутри \`DXButtonGroup\`:
+- Кнопка автоматически регистрируется в группе через \`provide/inject\`
+- Размер синхронизируется с размером группы (sm → sm, md → md, lg → lg)
+- Состояние \`disabled\` наследуется от группы
+- Border-radius адаптируется в зависимости от позиции (первая/последняя/средняя)
+- Визуальное состояние (selected/not selected) управляется группой
+- При клике с \`value\` prop, выбор обрабатывается через группу
+
+### Варианты оформления
+- **primary** - основная кнопка (темный фон)
+- **secondary** - вторичная кнопка (светлый фон)
+- **ghost** - прозрачная кнопка (без фона)
+- **outline** - кнопка с рамкой
+- **soft** - мягкая кнопка (светлый фон)
+- **link** - стиль ссылки
+- **success**, **warning**, **danger**, **info** - семантические варианты
+
+### Размеры
+Поддерживает 5 размеров:
+- **xs** - 28px высота
+- **sm** - 32px высота
+- **md** - 40px высота (по умолчанию)
+- **lg** - 48px высота
+- **xl** - 56px высота
+
+## Особенности
+
+### Режим iconOnly
+При \`iconOnly={true}\` кнопка становится квадратной (одинаковая ширина и высота),
+padding убирается, используется только размер иконки.
+
+### Режим block
+При \`block={true}\` кнопка растягивается на всю ширину контейнера (\`w-full\`).
+
+### Поддержка Vue Router
+При указании \`to\` prop, кнопка автоматически становится \`router-link\` и поддерживает
+все возможности Vue Router (навигация, активные состояния и т.д.).
+
+### Обычные ссылки
+При указании \`href\` prop, кнопка становится обычной ссылкой с поддержкой
+\`target\` и \`rel\` атрибутов для внешних ссылок.
+
+### Состояния
+- **disabled** - отключает кнопку (opacity-60, cursor-not-allowed)
+- **selected** (в группе) - визуально выделяет выбранную кнопку темным фоном
+
+### Обработка кликов
+- В группе с \`value\`: клик обрабатывается через группу, стандартное поведение предотвращается
+- Router-link/ссылка: стандартное поведение навигации
+- Обычная кнопка: стандартное поведение кнопки
+        `,
+      },
+    },
+  },
   argTypes: {
     variant: {
       control: 'select',