§AIKit ·

Библиотека UI-компонентов для AI-чатов, построенная на принципах атомарного дизайна.

§Описание

@gravity-ui/aikit — это гибкая и расширяемая библиотека React-компонентов для создания AI-чатов любой сложности. Библиотека предоставляет набор готовых компонентов, которые можно использовать как есть или кастомизировать под ваши нужды.

§Ключевые особенности

• 🎨 Атомарный дизайн — чёткая иерархия компонентов от атомов до страниц
• 🔧 Независимость от SDK — не привязана к конкретным AI SDK
• 🎭 Двухуровневый подход — готовые компоненты + хуки для кастомизации
• 🎨 CSS-переменные — простая кастомизация темы без переопределения компонентов
• 📦 TypeScript — полная типобезопасность из коробки
• 🔌 Расширяемость — система регистрации пользовательских типов сообщений

§Структура проекта

src/
├── components/
│   ├── atoms/          # Базовые неделимые UI-элементы
│   ├── molecules/      # Простые группы атомов
│   ├── organisms/      # Сложные компоненты с логикой
│   ├── templates/      # Готовые макеты
│   └── pages/          # Полные интеграции с данными
├── hooks/              # Хуки общего назначения
├── types/              # TypeScript-типы
├── utils/              # Утилиты
└── themes/             # CSS-темы и переменные

§Установка

npm install @gravity-ui/aikit

§Быстрый старт

import { ChatContainer } from '@gravity-ui/aikit';
import type { ChatType, TChatMessage } from '@gravity-ui/aikit';

function App() {
    const [messages, setMessages] = useState<TChatMessage[]>([]);
    const [chats, setChats] = useState<ChatType[]>([]);
    const [activeChat, setActiveChat] = useState<ChatType | null>(null);

    return (
        <ChatContainer
            chats={chats}
            activeChat={activeChat}
            messages={messages}
            onSendMessage={async (data) => {
                // Ваша логика отправки
                console.log('Сообщение:', data.content);
            }}
            onSelectChat={setActiveChat}
            onCreateChat={() => {
                // Создание нового чата
            }}
            onDeleteChat={(chat) => {
                // Удаление чата
            }}
        />
    );
}

§Архитектура

Библиотека построена на принципах атомарного дизайна:

§🔹 Атомы

Базовые неделимые UI-элементы без бизнес-логики:

• ActionButton — кнопка со встроенным тултипом
• Alert — сообщения с различными вариантами оформления
• ChatDate — форматирование даты с относительными датами
• ContextIndicator — индикатор использования контекста токенов
• ContextItem — метка контекста с возможностью удаления
• DiffStat — отображение статистики изменений кода
• Disclaimer — компонент текста-дисклеймера
• InlineCitation — текстовые цитаты
• Loader — индикатор загрузки
• MarkdownRenderer — рендерер Yandex Flavored Markdown
• MessageBalloon — обёртка сообщения
• Shimmer — эффект анимации загрузки
• SubmitButton — кнопка отправки с состояниями
• ToolIndicator — индикатор статуса выполнения инструмента

§🔸 Молекулы

Простые комбинации атомов:

• BaseMessage — базовая обёртка для всех типов сообщений
• ButtonGroup — группа кнопок с поддержкой ориентации
• InputContext — управление контекстом
• PromptInputBody — текстовое поле с авторастягиванием
• PromptInputFooter — футер с иконками действий и кнопкой отправки
• PromptInputHeader — хедер с элементами контекста и индикатором
• PromptInputPanel — панель-контейнер для пользовательского контента
• Suggestions — кликабельные кнопки предложений
• Tabs — навигационные вкладки с функцией удаления
• ToolFooter — футер сообщения инструмента с действиями
• ToolHeader — хедер сообщения инструмента с иконкой и действиями

§🔶 Организмы

Сложные компоненты с внутренней логикой:

• AssistantMessage — сообщение AI-ассистента
• Header — хедер чата
• MessageList — список сообщений
• PromptInput — поле ввода сообщения
• ThinkingMessage — процесс размышления AI
• ToolMessage — выполнение инструмента
• UserMessage — сообщение пользователя

§📄 Шаблоны

Готовые макеты:

• ChatContent — основной контент чата
• EmptyContainer — пустое состояние
• History — история чатов

§📱 Страницы

Полные интеграции:

• ChatContainer — полностью собранный чат

§Документация

• Руководство по быстрому старту
• Архитектура
• Структура проекта
• Руководство по тестированию
• Руководство по Playwright

§Тестирование

Проект использует Playwright Component Testing для визуального регрессионного тестирования.

§Запуск тестов

Важно: Все тесты должны запускаться через Docker для обеспечения консистентности скриншотов в различных окружениях.

# Запуск всех компонентных тестов в Docker (рекомендуется)
npm run playwright:docker

# Обновление эталонных скриншотов в Docker
npm run playwright:docker:update

# Запуск конкретного теста по grep-паттерну в Docker
npm run playwright:docker -- --grep "@ComponentName"

# Очистка кэша Docker при необходимости
npm run playwright:docker:clear-cache

§Локальное тестирование (только Linux)

Если вы работаете на Linux, вы можете запускать тесты локально:

# Установка браузеров Playwright (выполняется один раз)
npm run playwright:install

# Запуск всех компонентных тестов
npm run playwright

# Обновление эталонных скриншотов
npm run playwright:update

Подробная документация по тестированию доступна в Руководстве по Playwright.

§Разработка

Инструкции по разработке и контрибьютингу доступны в CONTRIBUTING.md.

§Лицензия

MIT