sfera-new/docs/presentation-layer/UI_COMPONENT_RULES.md

UI КОМПОНЕНТЫ СИСТЕМЫ SFERA

🎯 ОБЗОР UI СИСТЕМЫ

SFERA использует современную дизайн-систему основанную на Radix UI, Class Variance Authority (CVA) и Tailwind CSS с уникальным Glass Morphism стилем. Система включает 36 специализированных UI компонентов с полной типизацией TypeScript.

Архитектурные принципы:

• Headless UI - Radix UI для функциональности + кастомная стилизация
• Variant-driven - CVA для типизированных вариантов компонентов
• Glass Morphism - Современные полупрозрачные эффекты с backdrop-filter
• Accessibility First - Полная поддержка ARIA и клавиатурной навигации
• TypeScript Native - Строгая типизация всех props и вариантов

📦 ПОЛНЫЙ КАТАЛОГ КОМПОНЕНТОВ (36 компонентов)

🔘 1. BUTTON (button.tsx)

Описание: Основной интерактивный элемент с множественными вариантами дизайна.

interface ButtonProps {
  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link' | 'glass' | 'glass-secondary'
  size?: 'default' | 'sm' | 'lg' | 'icon'
  asChild?: boolean
}

Варианты стилей:

• default - основная фиолетовая кнопка bg-primary text-primary-foreground
• destructive - красная кнопка для опасных действий bg-destructive text-white
• outline - кнопка с границей border bg-background
• secondary - вторичная кнопка bg-secondary text-secondary-foreground
• ghost - прозрачная кнопка hover:bg-accent
• link - текстовая ссылка text-primary underline-offset-4
• glass - Glass Morphism стиль с градиентом
• glass-secondary - полупрозрачная Glass кнопка

Размеры:

• default - h-9 px-4 py-2 (36px высота)
• sm - h-8 px-3 (32px высота)
• lg - h-10 px-6 (40px высота)
• icon - size-9 (36x36px квадрат)

Пример использования:

<Button variant="glass" size="lg">
  Сохранить изменения
</Button>

🃏 2. CARD (card.tsx)

Описание: Контейнер для группировки связанного контента с составной архитектурой.

// Составные компоненты
<Card>
  <CardHeader>
    <CardTitle>Заголовок карточки</CardTitle>
    <CardDescription>Описание содержимого</CardDescription>
    <CardAction>Действие</CardAction>
  </CardHeader>
  <CardContent>
    Основное содержимое
  </CardContent>
  <CardFooter>
    Нижняя часть
  </CardFooter>
</Card>

CSS классы:

• Card: bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm
• CardHeader: Использует CSS Grid для автоматического позиционирования
• CardTitle: leading-none font-semibold
• CardDescription: text-muted-foreground text-sm

⌨️ 3. INPUT (input.tsx)

Описание: Поле ввода текста с поддержкой Glass Morphism и состояний фокуса.

interface InputProps extends React.ComponentProps<'input'> {
  // Стандартные HTML input props
}

// Два варианта стилизации
<Input placeholder="Стандартное поле" />
<GlassInput placeholder="Glass Morphism поле" />

Стили Input:

• Базовый класс: h-9 w-full rounded-md border bg-transparent px-3 py-1
• Фокус: focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]
• Ошибка: aria-invalid:ring-destructive/20 aria-invalid:border-destructive

Стили GlassInput:

• Базовый класс: glass-input text-white placeholder:text-white/60
• Размеры: h-11 rounded-lg px-4 py-3 (больше обычного input)
• Эффекты: полупрозрачный фон с backdrop-filter

🏷️ 4. BADGE (badge.tsx)

Описание: Небольшие метки для отображения статуса, категорий или счетчиков.

interface BadgeProps {
  variant?: 'default' | 'secondary' | 'destructive' | 'outline'
  asChild?: boolean
}

Варианты:

• default - bg-primary text-primary-foreground
• secondary - bg-secondary text-secondary-foreground
• destructive - bg-destructive text-white
• outline - text-foreground border (прозрачный фон)

Базовые стили:

• Размер: px-2 py-0.5 text-xs font-medium
• Форма: rounded-md border
• Поддержка иконок: [&>svg]:size-3 gap-1

📊 5. PROGRESS (progress.tsx)

Описание: Индикатор прогресса для отображения выполнения задач.

<Progress value={75} className="w-full" />

📱 6. ALERT (alert.tsx)

Описание: Компонент для отображения важных сообщений пользователю.

<Alert>
  <AlertTitle>Внимание</AlertTitle>
  <AlertDescription>Важное сообщение для пользователя</AlertDescription>
</Alert>

🗂️ 7. TABS (tabs.tsx)

Описание: Система вкладок для переключения между разными представлениями.

<Tabs defaultValue="tab1">
  <TabsList>
    <TabsTrigger value="tab1">Вкладка 1</TabsTrigger>
    <TabsTrigger value="tab2">Вкладка 2</TabsTrigger>
  </TabsList>
  <TabsContent value="tab1">Содержимое 1</TabsContent>
  <TabsContent value="tab2">Содержимое 2</TabsContent>
</Tabs>

Особенности стилизации:

• Список вкладок: Glass Morphism фон background: rgba(255, 255, 255, 0.12)
• Активная вкладка: background: rgba(255, 255, 255, 0.2) с белым текстом
• Hover эффект: background: rgba(255, 255, 255, 0.1)

📝 8. TEXTAREA (textarea.tsx)

Описание: Многострочное поле ввода текста.

<Textarea placeholder="Введите текст..." rows={4} />

☑️ 9. CHECKBOX (checkbox.tsx)

Описание: Чекбокс для выбора опций.

<Checkbox checked={isChecked} onCheckedChange={setIsChecked} />

🎚️ 10. SWITCH (switch.tsx)

Описание: Переключатель для включения/выключения функций.

<Switch checked={isEnabled} onCheckedChange={setIsEnabled} />

🎚️ 11. SLIDER (slider.tsx)

Описание: Ползунок для выбора числовых значений.

<Slider defaultValue={[50]} max={100} step={1} />

📅 12. CALENDAR (calendar.tsx)

Описание: Компонент календаря для выбора дат.

<Calendar mode="single" selected={date} onSelect={setDate} />

📅 13. DATE-PICKER (date-picker.tsx)

Описание: Поле выбора даты с календарем.

<DatePicker value={date} onChange={setDate} />

📅 14. GLASS-DATE-PICKER (glass-date-picker.tsx)

Описание: Date picker в Glass Morphism стиле.

<GlassDatePicker value={date} onChange={setDate} />

📋 15. SELECT (select.tsx)

Описание: Выпадающий список для выбора опций.

<Select value={value} onValueChange={setValue}>
  <SelectTrigger>
    <SelectValue placeholder="Выберите опцию" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="option1">Опция 1</SelectItem>
    <SelectItem value="option2">Опция 2</SelectItem>
  </SelectContent>
</Select>

📋 16. GLASS-SELECT (glass-select.tsx)

Описание: Select в Glass Morphism стиле для темных фонов.

🏷️ 17. LABEL (label.tsx)

Описание: Метки для полей форм с accessibility.

<Label htmlFor="email">Email адрес</Label>
<Input id="email" type="email" />

👤 18. AVATAR (avatar.tsx)

Описание: Отображение аватаров пользователей с fallback.

<Avatar>
  <AvatarImage src="/avatar.jpg" alt="User" />
  <AvatarFallback>JD</AvatarFallback>
</Avatar>

🌐 19. DIALOG (dialog.tsx)

Описание: Модальные окна для важного контента.

<Dialog>
  <DialogTrigger>Открыть диалог</DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Заголовок</DialogTitle>
      <DialogDescription>Описание</DialogDescription>
    </DialogHeader>
    <DialogFooter>
      <Button>Сохранить</Button>
    </DialogFooter>
  </DialogContent>
</Dialog>

⚠️ 20. ALERT-DIALOG (alert-dialog.tsx)

Описание: Критичные диалоги подтверждения.

<AlertDialog>
  <AlertDialogTrigger>Удалить</AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Подтвердите удаление</AlertDialogTitle>
      <AlertDialogDescription>
        Это действие нельзя отменить.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Отмена</AlertDialogCancel>
      <AlertDialogAction>Удалить</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

💬 21. POPOVER (popover.tsx)

Описание: Всплывающие элементы для дополнительного контента.

<Popover>
  <PopoverTrigger>Показать информацию</PopoverTrigger>
  <PopoverContent>
    Дополнительная информация
  </PopoverContent>
</Popover>

📱 22. DROPDOWN-MENU (dropdown-menu.tsx)

Описание: Выпадающие меню для действий и навигации.

<DropdownMenu>
  <DropdownMenuTrigger>Меню</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>Действие 1</DropdownMenuItem>
    <DropdownMenuSeparator />
    <DropdownMenuItem>Действие 2</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>

➖ 23. SEPARATOR (separator.tsx)

Описание: Визуальные разделители контента.

<Separator orientation="horizontal" />
<Separator orientation="vertical" />

📱 24. PHONE-INPUT (phone-input.tsx)

Описание: Специализированное поле для ввода номеров телефонов.

<PhoneInput value={phone} onChange={setPhone} />

💀 25. SKELETON (skeleton.tsx)

Описание: Плейсхолдеры для загружающегося контента.

<Skeleton className="h-4 w-full" />
<Skeleton className="h-8 w-8 rounded-full" />

🛒 26. PRODUCT-CARD-SKELETON (product-card-skeleton.tsx)

Описание: Специализированный скелетон для карточек товаров.

<ProductCardSkeleton />

⏳ 27. LOADING-FALLBACK (loading-fallback.tsx)

Описание: Компонент загрузки для асинхронного контента.

<LoadingFallback text="Загрузка данных..." />

🎵 МЕДИА КОМПОНЕНТЫ

🎤 28. VOICE-RECORDER (voice-recorder.tsx)

Описание: Запись голосовых сообщений с реального времени UI.

<VoiceRecorder onRecordingComplete={handleRecording} />

▶️ 29. VOICE-PLAYER (voice-player.tsx)

Описание: Воспроизведение аудио сообщений с прогресс-баром.

<VoicePlayer audioUrl="/audio.mp3" duration={30} />

🖼️ 30. IMAGE-MESSAGE (image-message.tsx)

Описание: Отображение изображений в сообщениях.

<ImageMessage src="/image.jpg" alt="Сообщение" />

🔍 31. IMAGE-LIGHTBOX (image-lightbox.tsx)

Описание: Полноэкранный просмотр изображений.

<ImageLightbox images={imageUrls} initialIndex={0} />

📄 32. FILE-MESSAGE (file-message.tsx)

Описание: Отображение файловых вложений.

<FileMessage fileName="document.pdf" fileSize={1024000} fileUrl="/file.pdf" />

📤 33. FILE-UPLOADER (file-uploader.tsx)

Описание: Загрузка файлов с drag & drop.

<FileUploader onFileSelect={handleFiles} accept=".pdf,.doc,.docx" />

😀 34. EMOJI-PICKER (emoji-picker.tsx)

Описание: Выбор эмодзи для сообщений.

<EmojiPicker onEmojiSelect={handleEmojiSelect} />

📊 35. CHART (chart.tsx)

Описание: Компоненты для отображения графиков и диаграмм.

<Chart data={chartData} type="line" />

🔔 36. SONNER (sonner.tsx)

Описание: Система toast уведомлений.

import { toast } from 'sonner'

toast.success('Операция выполнена успешно')
toast.error('Произошла ошибка')
toast.info('Информационное сообщение')

📊 КАСТОМНЫЕ ТАБЛИЦЫ СИСТЕМЫ

🏷️ 37. MULTILEVEL SUPPLIES TABLE (multilevel-supplies-table.tsx)

Описание: Многоуровневая таблица поставок для кабинета селлера в разделе "Мои поставки".

Интерфейсы:

interface MultiLevelSuppliesTableProps {
  supplies?: SupplyOrderFromGraphQL[]
  loading?: boolean
  userRole?: 'SELLER' | 'WHOLESALE' | 'FULFILLMENT' | 'LOGIST'
  onSupplyAction?: (supplyId: string, action: string) => void
}

interface SupplyOrderFromGraphQL {
  id: string
  organizationId: string
  partnerId: string
  partner: {
    id: string
    name?: string
    fullName?: string
    inn: string
    address?: string
    type: string
  }
  deliveryDate: string
  status: string
  totalAmount: number
  totalItems: number
  fulfillmentCenter?: {
    id: string
    name?: string
    address?: string
  }
  routes: Route[]
  items: SupplyItem[]
  createdAt: string
}

Особенности:

• Трехуровневая структура: Поставка → Маршруты → Товары
• Раскрываемые/сворачиваемые уровни
• Различные представления для разных ролей пользователей
• Glass morphism дизайн с полупрозрачными карточками

Использование:

<MultiLevelSuppliesTable
  supplies={suppliesData}
  loading={isLoading}
  userRole="SELLER"
  onSupplyAction={(id, action) => handleSupplyAction(id, action)}
/>

📦 38. GOODS SUPPLIES TABLE (goods-supplies-table.tsx)

Описание: Таблица товарных поставок с детальной структурой.

Интерфейсы:

interface GoodsSuppliesTableProps {
  supplies?: GoodsSupply[]
  loading?: boolean
  onActionClick?: (supplyId: string, action: string) => void
}

interface GoodsSupply {
  id: string
  number: string
  creationMethod: 'cards' | 'suppliers' // 📱 карточки / 🏢 поставщик
  date: string
  status: SupplyStatus
  totalAmount: number
  routes: GoodsSupplyRoute[]
}

interface GoodsSupplyRoute {
  id: string
  from: string
  fromAddress: string
  to: string
  toAddress: string
  wholesalers: GoodsSupplyWholesaler[]
  totalProductPrice: number
  fulfillmentServicePrice: number
  logisticsPrice: number
  totalAmount: number
}

interface GoodsSupplyProduct {
  id: string
  name: string
  sku: string
  category: string
  plannedQty: number
  actualQty: number
  defectQty: number
  productPrice: number
  parameters: ProductParameter[]
}

Особенности:

• Четырехуровневая структура: Поставка → Маршрут → Поставщик → Товар
• Детальная информация по каждому уровню
• Цветовая индикация статусов
• Расчет итоговых сумм на каждом уровне
• Поддержка параметров товаров

Статусы поставок:

type SupplyStatus =
  | 'new' // Новая
  | 'confirmed' // Подтверждена
  | 'in_transit' // В пути
  | 'at_fulfillment' // На фулфилменте
  | 'in_processing' // В обработке
  | 'completed' // Завершена
  | 'cancelled' // Отменена
  | 'issue' // Проблема

Использование:

<GoodsSuppliesTable
  supplies={goodsSupplies}
  loading={isLoading}
  onActionClick={(id, action) => {
    if (action === 'view') navigateToDetails(id)
    if (action === 'cancel') cancelSupply(id)
  }}
/>

🎨 ДИЗАЙН-СИСТЕМА КОМПОНЕНТОВ

Унифицированные props:

// Большинство компонентов поддерживают:
interface CommonProps {
  className?: string // Дополнительные CSS классы
  asChild?: boolean // Использование как Slot от Radix
  'data-slot'?: string // Автоматический слот для идентификации
}

Паттерн CVA (Class Variance Authority):

const componentVariants = cva(
  'базовые-классы', // Общие стили для всех вариантов
  {
    variants: {
      variant: {
        // Варианты дизайна
        default: 'стили-по-умолчанию',
        secondary: 'вторичные-стили',
      },
      size: {
        // Размеры
        sm: 'маленький-размер',
        lg: 'большой-размер',
      },
    },
    defaultVariants: {
      // Значения по умолчанию
      variant: 'default',
      size: 'default',
    },
  },
)

Accessibility Features:

• ARIA Support - все компоненты поддерживают ARIA атрибуты
• Keyboard Navigation - полная навигация с клавиатуры
• Focus Management - логичное управление фокусом
• Screen Reader - совместимость с программами чтения экрана

Glass Morphism Effects:

.glass-card {
  background: rgba(255, 255, 255, 0.12);
  backdrop-filter: blur(20px);
  border: 1px solid rgba(255, 255, 255, 0.2);
  box-shadow: 0 8px 32px rgba(168, 85, 247, 0.18);
}

.glass-input {
  background: rgba(255, 255, 255, 0.08);
  backdrop-filter: blur(12px);
  border: 1px solid rgba(255, 255, 255, 0.15);
}

.glass-button {
  background: linear-gradient(135deg, rgba(168, 85, 247, 0.9) 0%, rgba(59, 130, 246, 0.85) 100%);
  backdrop-filter: blur(20px);
}

🔧 ПРАВИЛА ИСПОЛЬЗОВАНИЯ

1. Типизация компонентов

// ✅ Правильно - с типизацией
<Button variant="glass" size="lg" onClick={handleClick}>
  Действие
</Button>

// ❌ Неправильно - без типизации
<button className="some-custom-class">
  Действие
</button>

2. Композиция сложных компонентов

// ✅ Правильно - составная структура
<Card>
  <CardHeader>
    <CardTitle>Заказ #1234</CardTitle>
    <CardAction>
      <Button size="sm">Детали</Button>
    </CardAction>
  </CardHeader>
  <CardContent>
    <p>Описание заказа</p>
  </CardContent>
</Card>

// ❌ Неправильно - плоская структура
<div className="card">
  <h3>Заказ #1234</h3>
  <p>Описание заказа</p>
</div>

3. Glass Morphism для темных фонов

// ✅ Правильно - Glass компоненты на темном фоне
<div className="bg-gradient-cosmic">
  <GlassInput placeholder="Поиск..." />
  <Button variant="glass">Найти</Button>
</div>

// ❌ Неправильно - обычные компоненты на темном фоне
<div className="bg-black">
  <Input placeholder="Поиск..." />  {/* Не видно */}
</div>

4. Accessibility обязателен

// ✅ Правильно - с accessibility
<Label htmlFor="email">Email</Label>
<Input
  id="email"
  type="email"
  aria-describedby="email-error"
  aria-invalid={hasError}
/>
{hasError && <span id="email-error">Неверный формат email</span>}

// ❌ Неправильно - без accessibility
<span>Email</span>
<input type="email" />

5. Состояния загрузки

// ✅ Правильно - скелетоны для загрузки
{loading ? (
  <ProductCardSkeleton />
) : (
  <ProductCard data={product} />
)}

// ❌ Неправильно - пустая область
{loading ? null : <ProductCard data={product} />}

📱 АДАПТИВНОСТЬ

Responsive Breakpoints:

• sm - 640px и выше
• md - 768px и выше
• lg - 1024px и выше
• xl - 1280px и выше

Mobile-First подход:

// ✅ Правильно
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">
  {items.map(item => <Card key={item.id}>{item.name}</Card>)}
</div>

// ❌ Неправильно
<div className="grid-cols-3"> {/* Не адаптивно */}

🚀 ПРОИЗВОДИТЕЛЬНОСТЬ

Lazy Loading компонентов:

const HeavyComponent = lazy(() => import('./heavy-component'))

// Использование с Suspense
<Suspense fallback={<LoadingFallback />}>
  <HeavyComponent />
</Suspense>

Мемоизация дорогих вычислений:

const ExpensiveComponent = memo(({ data }) => {
  const processedData = useMemo(() =>
    processLargeDataset(data), [data]
  )

  return <Chart data={processedData} />
})

---

UI компоненты задокументированы на основе анализа 36 файлов в src/components/ui/
Версия документа: 2025-08-21
Основа: Radix UI + CVA + Tailwind CSS + Glass Morphism