Skip to main content

Архитектура UI-кита

Архитектура UI-кита (@lowcode/ui-kit)

Как устроена библиотека компонентов: тема, примитивы, layout-блоки и их роль в редакторе.

🎯 Задача страницы​

Эта страница описывает архитектуру пакета @lowcode/ui-kit:

  • какую роль он играет в общей системе;
  • как устроены слои темы, примитивов и layout-компонентов;
  • как используется Tailwind CSS;
  • как UI-кит интегрируется в builder-web;
  • где искать код и как добавлять новые компоненты.

1. Роль @lowcode/ui-kit в общей архитектуре​

@lowcode/ui-kit — это общая библиотека React-компонентов для всей платформы:

  • задаёт визуальный стиль редактора (builder-web) и других UI-частей;
  • предоставляет темизацию (light/dark) через ThemeProvider;
  • содержит набор примитивов (Button, Input, Select, и т.п.);
  • предоставляет layout-компоненты для построения каркаса редактора (AppShell, Sidebar, PropsPanel, CanvasContainer, PreviewContainer);
  • не содержит бизнес-логики и ничего не знает про DSL / проекты / API.

Высокоуровневая схема взаимодействия:

graph TD
  subgraph UI
    BW[builder-web]
    RH[runtime-host UI]
  end

  subgraph UIKIT[@lowcode/ui-kit]
    THEME[ThemeProvider<br/>+ токены тем]
    PRIM[Примитивы<br/>(Button, Input, ...)]
    LAYOUT[Layout-компоненты<br/>(AppShell, Sidebar, ...)]
  end

  BW --> UIKIT
  RH --> UIKIT
  UIKIT --> THEME
  UIKIT --> PRIM
  UIKIT --> LAYOUT

Все компоненты builder-web строятся поверх @lowcode/ui-kit, а не реализуют стили самостоятельно.

2. Общая структура пакета​

Высокоуровневая структура packages/ui-kit:

packages/ui-kit/
  src/
    index.ts               ← публичный API пакета

    theme/                 ← система темы (light/dark)
      ThemeTypes.ts
      tokens.ts
      ThemeProvider.tsx

    components/
      primitives/          ← базовые контролы
        Button.tsx
        Input.tsx
        Textarea.tsx
        Checkbox.tsx
        Switch.tsx
        Select.tsx
        Badge.tsx
        Spinner.tsx

      layout/              ← layout- и editor-паттерны
        AppShell.tsx
        AppHeader.tsx
        Sidebar.tsx
        PropsPanel.tsx
        Panel.tsx
        Card.tsx
        ScrollArea.tsx
        CanvasContainer.tsx
        PreviewContainer.tsx

    styles/
      base.css             ← слой Tailwind (base/components/utilities)

    utils/
      cn.ts                ← helper для склейки классов
  • Все публичные сущности реэкспортируются из src/index.ts.
  • Типы и функции, попадающие в документацию typedoc, задокументированы через JSDoc/Typedoc-комментарии на русском.

Основные точки входа в reference-документации:

  • общий обзор пакета — @lowcode/ui-kit;
  • модуль темы — theme;
  • примитивы — components/primitives;
  • layout — components/layout.

3. Система тем и ThemeProvider​

3.1. Типы и токены темы​

Базовые типы и набор токенов описаны в:

  • ThemeName — имя темы ("light" | "dark");
  • ThemeTokens — семантические цветовые токены для одной темы;
  • lightTheme, darkTheme, DEFAULT_THEME_NAME — экспортируются из tokens.ts.

Архитектурно тема описывается семантическими цветами (background, surface, text, primary, danger и т.п.), а не “сырыми” токенами Tailwind.

3.2. ThemeProvider и жизненный цикл темы​

Компонент ThemeProvider:

  • хранит текущую тему в React-состоянии;

  • при инициализации читает выбранную тему из localStorage;

  • синхронизирует изменения темы обратно в localStorage;

  • выставляет:

    • атрибут data-theme="light" | "dark" на корневой div,
    • класс dark при активной тёмной теме;

  • через это Tailwind получает возможность применять dark:-классы.

Хук useTheme предоставляет интерфейс:

  • themeName: ThemeName — текущее имя темы;
  • theme: ThemeTokens — объект токенов темы;
  • setTheme(name: ThemeName) — установка конкретной темы;
  • toggleTheme() — переключение между light/dark.

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

<ThemeProvider>
  <App />
</ThemeProvider>

4. Примитивы​

Примитивы UI-кита описаны в модуле components/primitives.

Сюда входят:

Все они используют Tailwind-классы и полностью совместимы с темизацией.

5. Layout-компоненты​

components/layout содержит компоненты каркаса редактора:

Эти компоненты образуют каркас для builder-web, но остаются независимыми от DSL.

6. Tailwind и сборка CSS​

ui-kit не компилирует Tailwind сам. Он лишь поставляет:

  • src/styles/base.css с:

    @tailwind base;
    @tailwind components;
    @tailwind utilities;

  • React-компоненты, использующие Tailwind-классы.

Генерацию CSS выполняет host-приложение (builder-web).

Tailwind в builder-web видит классы UI-кита благодаря настройке:

content: ['./src/**/*.{ts,tsx}', '../../packages/ui-kit/src/**/*.{ts,tsx}'];

Это позволяет ui-kit оставаться полностью headless и переиспользуемым.

7. Где искать ключевые части кода​

| Компонент / слой | Путь | Reference-документация |