Продвинутый рабочий процесс

Цель и область применения

Этот документ охватывает нестандартные сценарии, когда 15 составных UI-компонентов из src/components/ui/ недостаточны для вашей задачи. Вы узнаете, как компоновать пять базовых примитивов (Block, Box, Grid, Flex, Stack) из src/core/ui/ для создания пользовательских интерфейсов. Для типичного использования компонентов с готовыми композитами см. Базовый рабочий процесс. Для общих рекомендаций по использованию и паттернов см. Лучшие практики. Источники: .devin/wiki.json191-198 src/components/GUIDE_CREATE_FORM.md1-10

Когда использовать продвинутый рабочий процесс

Библиотека предоставляет 15 составных компонентов, которые покрывают ~80% обычных сценариев UI. Однако некоторые элементы намеренно отсутствуют в библиотеке:

Отсутствующий тип компонента	Причина отсутствия	Продвинутое решение
Элементы форм (Form, Label, Input)	HTML-семантика сильно варьируется	Компоновать `Block` + `Box` с пропом `component`
Выпадающие списки Select	Требуется сложное управление состоянием	Использовать `Box component="select"` с вариантами
Пользовательские интерактивные виджеты	Специфическая для приложения логика	Строить с помощью примитивов + вариантов
Нестандартные макеты	Уникальные структурные требования	Компоновать `Grid`, `Flex`, `Stack` напрямую

Дерево решений: Базовый vs Продвинутый рабочий процесс

Да

Нет

Да

Нет

Да

Нет

Нужен UI-элемент

Компонент существует в
src/components/ui/?

Использовать составной компонент
(Button, Card, Badge)

Стандартный HTML-элемент
со стилизацией?

Использовать Block/Box
с пропом component

Сложная структура
макета?

Компоновать Grid/Flex/Stack
с примитивами

Создать пользовательский компонент
из примитивов

Базовый рабочий процесс (5.1)

Продвинутый рабочий процесс (5.2)

Источники: src/components/README.md1-8 src/components/GUIDE_CREATE_FORM.md5-10

Построение форм с помощью Block и Box

Библиотека не включает специализированные компоненты Form, Label или Input. Вместо этого используйте полиморфный проп component на Block и Box для рендеринга семантических HTML-элементов с полной системой вариантов.

Паттерн пропа component

Проп component преобразует примитивы в любой HTML-элемент, сохраняя типобезопасные пропы вариантов:

Пропы вариантов

Отрендеренные элементы

проп component

Примитивные компоненты

применяется к

применяется к

применяется к

применяется к

Block
(семантический контейнер)

Box
(гибкий примитив)

component='form'

component='label'

component='input'

component='textarea'

component='select'

<form>

<label>

<input>

<textarea>

<select>

p, m, px, py, и т.д.

w, h, maxW, minH

rounded, border, shadow

bg, c, borderColor

Источники: src/components/GUIDE_CREATE_FORM.md7-9

Паттерн структуры формы

Используйте Block с component="form" как обёртку формы, применяя варианты макета и стилизации: Структура контейнера формы:

Элемент	Компонент	Пропы	Назначение
Обёртка формы	`<Block component="form">`	`w`, `maxW`, `p`, `rounded`, `shadow`, `bg`	Семантический контейнер формы с макетом
Группы полей	`<Block>`	`w="full"`, `className="space-y-2"`	Вертикальное расстояние между полями
Метки	`<Box component="label">`	`c`, `className="text-sm font-medium"`	Доступные метки полей
Поля ввода	`<Box component="input">`	`w="full"`, `p`, `rounded`, `border`, `borderColor`	Поля ввода формы
Текстовые области	`<Box component="textarea">`	`w="full"`, `p`, `rounded`, `border`, `minH`	Многострочный ввод текста
Кнопка отправки	`<Button>`	`w="full"`, `size`, `variant`	Отправка формы

Пример структуры формы (см. src/components/GUIDE_CREATE_FORM.md14-32):

<Block 
  component="form"
  w="full"
  maxW="md"
  p="lg"
  rounded="lg"
  shadow="md"
  bg="white"
>
  {/* Поля формы */}
</Block>

Источники: src/components/GUIDE_CREATE_FORM.md11-33

Паттерны полей ввода

Все типы ввода используют Box с component="input" и стандартными HTML-атрибутами: Текстовое поле (src/components/GUIDE_CREATE_FORM.md37-50):

<Box 
  component="input"
  type="text"
  placeholder="Enter your name"
  w="full"
  p="md"
  rounded="md"
  border="default"
  borderColor="gray-300"
/>

Поле с состояниями фокуса (src/components/GUIDE_CREATE_FORM.md54-67):

<Box 
  component="input"
  type="text"
  w="full"
  p="md"
  rounded="lg"
  border="default"
  bg="white"
  c="gray-900"
  className="focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
/>

Поле пароля (src/components/GUIDE_CREATE_FORM.md70-82):

<Box 
  component="input"
  type="password"
  placeholder="Password"
  w="full"
  p="md"
  rounded="md"
  border="default"
  borderColor="gray-300"
/>

Числовое поле с ограничениями (src/components/GUIDE_CREATE_FORM.md84-97):

<Box 
  component="input"
  type="number"
  placeholder="Age"
  w="full"
  p="md"
  rounded="md"
  border="default"
  min={0}
  max={120}
/>

Источники: src/components/GUIDE_CREATE_FORM.md35-97

Поля Textarea

Используйте Box с component="textarea" для многострочного ввода текста: Базовая текстовая область (src/components/GUIDE_CREATE_FORM.md99-115):

<Box 
  component="textarea"
  rows={4}
  placeholder="Enter your message"
  w="full"
  p="md"
  rounded="md"
  border="default"
  borderColor="gray-300"
  className="resize-none"
/>

Текстовая область с минимальной высотой (src/components/GUIDE_CREATE_FORM.md117-129):

<Box 
  component="textarea"
  placeholder="Description"
  w="full"
  p="md"
  rounded="lg"
  border="default"
  minH="32"
  className="resize-y"
/>

Источники: src/components/GUIDE_CREATE_FORM.md99-129

Полный пример формы

Архитектура контактной формы:

Block component='form'
обработчик onSubmit
Макет: w='full' maxW='lg' p='lg'
Стиль: rounded='lg' shadow='lg' bg='white'

Block (группа поля имени)
w='full' space-y-2

Box component='label'
c='gray-700' text-sm font-medium

Box component='input'
type='text' name='name' required
w='full' p='md' rounded='md'
border='default' borderColor='gray-300'

Block (группа поля email)
w='full' space-y-2

Box component='label'
c='gray-700' text-sm font-medium

Box component='input'
type='email' name='email' required
w='full' p='md' rounded='md'

Block (группа поля сообщения)
w='full' space-y-2

Box component='label'
c='gray-700' text-sm font-medium

Box component='textarea'
rows=5 name='message' required
w='full' p='md' minH='32'
resize-none focus:ring-2

Button type='submit'
w='full' size='lg' variant='default'

Полная реализация в src/components/GUIDE_CREATE_FORM.md134-226 Ключевые паттерны:

Обработка событий формы: проп onSubmit на форме Block
Структура полей: обёртка Block → метка → поле ввода в каждой группе
Расстояния: className="space-y-6" на форме, className="space-y-2" на группах полей
Валидация: атрибут required на полях ввода
Состояния фокуса: комбинация вариантов с className для колец фокуса

Источники: src/components/GUIDE_CREATE_FORM.md131-226

Многоколоночный макет формы

Для сложных форм используйте Box с grid-отображением (src/components/GUIDE_CREATE_FORM.md228-277):

<Block 
  component="form"
  w="full"
  maxW="2xl"
  p="lg"
  rounded="lg"
  shadow="md"
  bg="white"
>
  <Box 
    display="grid" 
    className="grid-cols-1 md:grid-cols-2 gap-6"
  >
    {/* Поле имени */}
    <Block className="space-y-2">
      <Box component="label" className="text-sm font-medium">
        First Name
      </Box>
      <Box 
        component="input"
        type="text"
        w="full"
        p="md"
        rounded="md"
        border="default"
      />
    </Block>

    {/* Поле фамилии */}
    <Block className="space-y-2">
      <Box component="label" className="text-sm font-medium">
        Last Name
      </Box>
      <Box 
        component="input"
        type="text"
        w="full"
        p="md"
        rounded="md"
        border="default"
      />
    </Block>
  </Box>
</Block>

Источники: src/components/GUIDE_CREATE_FORM.md228-277

Паттерн валидации формы

Создавайте переиспользуемые компоненты полей с валидацией (src/components/GUIDE_CREATE_FORM.md311-339):

function ValidatedInput({ error, label, ...props }) {
  return (
    <Block w="full" className="space-y-2">
      <Box component="label" c="gray-700" className="text-sm font-medium">
        {label}
      </Box>
      <Box 
        component="input"
        w="full"
        p="md"
        rounded="md"
        border="default"
        borderColor={error ? "red-500" : "gray-300"}
        bg={error ? "red-50" : "white"}
        className={error ? "focus:ring-red-500" : "focus:ring-blue-500"}
        {...props}
      />
      {error && (
        <Box c="red-600" className="text-sm">
          {error}
        </Box>
      )}
    </Block>
  );
}

Разбор паттерна:

Условные borderColor и bg на основе состояния ошибки
Динамические цвета кольца фокуса через className
Отображение сообщения об ошибке с Box для цвета текста
Распространение пропов с {...props} для HTML-атрибутов

Источники: src/components/GUIDE_CREATE_FORM.md311-339

Доступные пропы вариантов для примитивов

Все примитивы поддерживают 12 категорий вариантов CVA. Ключевые варианты для построения форм:

Варианты расстояний

Проп	Значения	Назначение
`p`, `px`, `py`, `pt`, `pb`, `pl`, `pr`	`none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`	Управление padding
`m`, `mx`, `my`, `mt`, `mb`, `ml`, `mr`	`none`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `auto`	Управление margin

Варианты макета

Проп	Значения	Назначение
`w`	`auto`, `full`, `screen`, `fit`, `min`, `max`, `1/2`, `1/3`, и т.д.	Управление шириной
`h`	`auto`, `full`, `screen`, `fit`, `min`, `max`	Управление высотой
`minH`	Числовые значения типа `"32"`, `"64"`	Минимальная высота (полезно для textarea)
`maxW`	`xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, и т.д.	Максимальная ширина (полезно для центрированных форм)
`display`	`block`, `flex`, `grid`, `inline`, `none`	Тип отображения

Варианты границ и стиля

Проп	Значения	Назначение
`border`	`none`, `default`, `2`, `4`, `8`	Ширина границы
`borderColor`	Все цвета дизайн-системы	Цвет границы
`rounded`	`none`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `full`	Радиус скругления
`shadow`	`none`, `sm`, `md`, `lg`, `xl`, `2xl`	Тень блока

Варианты цвета

Проп	Значения	Назначение
`bg`	Все цвета дизайн-системы (напр., `white`, `card`, `gray-50`)	Цвет фона
`c`	Все цвета дизайн-системы (напр., `gray-700`, `red-600`)	Цвет текста

Источники: src/components/GUIDE_CREATE_FORM.md279-301 src/components/README.md205-222

Лучшие практики для продвинутой компоновки

Гибридный паттерн Вариант + className

Система вариантов покрывает ~80% потребностей в стилизации. Для оставшихся 20% комбинируйте варианты с className:

<Box 
  component="input"
  // Варианты покрывают структуру
  w="full"
  p="md"
  rounded="md"
  border="default"
  bg="white"
  // className покрывает интерактивные состояния
  className="focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
/>

Когда использовать className:

Интерактивные состояния (:hover, :focus, :active)
Псевдоэлементы (:before, :after)
Сложные анимации
Grid/flex утилиты, не покрытые вариантами
Точки останова адаптивности за пределами системы вариантов

Источники: src/components/GUIDE_CREATE_FORM.md302-310 src/components/README.md237-244

Пользовательская компоновка компонентов

Создание переиспользуемых композитов

Когда вам нужен один и тот же паттерн многократно, извлеките его в пользовательский компонент: Паттерн: Поле ввода с меткой

управляет

отображает

рендерит

Пользовательский компонент ValidatedInput

Обёртка Block
w='full' space-y-2

Box component='label'
c='gray-700'
text-sm font-medium

Box component='input'
w='full' p='md'
rounded='md' border='default'
Условно: borderColor, bg

Box (условный рендер)
c='red-600' text-sm
Отображает сообщение об ошибке

Пропы:
- error (string | undefined)
- label (string)
- ...props (HTML-атрибуты)

Подход к реализации:

Принимать пропы вариантов и HTML-атрибуты через распространение пропов
Обрабатывать условную логику (состояния ошибок, валидация)
Поддерживать доступность (ассоциации меток, ARIA-атрибуты)
Возвращать компоновку примитивов (Block + Box)

Источники: src/components/GUIDE_CREATE_FORM.md311-339

Нестандартные пользовательские сценарии, не связанные с формами

Пользовательские интерактивные виджеты: При создании специфичных для приложения виджетов (слайдеры, пикеры, пользовательские элементы управления):

Начинайте с Box или Block как контейнера
Применяйте семантический проп component (<Box component="button"> для кликабельных элементов)
Используйте пропы вариантов для макета и стилизации
Добавляйте обработчики событий (onClick, onChange, и т.д.)
Комбинируйте с className для сложных взаимодействий

Пользовательские структуры макета: Для уникальных требований к макету, не покрытых DashLayout, LayoutBlock или SplitBlock:

Компонуйте Grid, Flex или Stack из src/core/ui/
Применяйте варианты макета (cols, gap, align, justify)
Вкладывайте примитивы для иерархической структуры
Используйте Block с component="section"/component="aside" для семантической разметки

Источники: src/components/README.md237-244 .devin/wiki.json191-198

Сравнение: Базовый vs Продвинутый рабочий процесс

Когда использовать каждый подход:

Продвинутый рабочий процесс (5.2)

Базовый рабочий процесс (5.1)

Да

Нет

Готовые компоненты существуют

Card, Button, Badge,
Title, Text, Image, Icon

Использовать составные компоненты
из src/components/ui/

Пример:
<Card p='lg' rounded='xl'>

Пользовательские требования

Элементы форм, пользовательские виджеты,
уникальные макеты

Компоновать примитивы
из src/core/ui/

Пример:
<Block component='form'>
<Box component='input'/>

Компонент существует
в библиотеке?

Матрица возможностей:

Особенность	Базовый рабочий процесс	Продвинутый рабочий процесс
Скорость разработки	Быстрая (готовые компоненты)	Умеренная (ручная компоновка)
Гибкость	Ограничена пропами компонентов	Полный контроль через примитивы
Поддержка кода	Проще (меньше компонентов)	Более сложная (больше кода)
Типобезопасность	Полная (типы составных компонентов)	Полная (типы примитивных компонентов)
Поддержка вариантов	Через пробрасывание пропов	Прямое применение
Семантический HTML	Предопределённая структура	Полный контроль через проп `component`
Лучше всего для	Стандартных UI-паттернов	Пользовательских/уникальных требований

Источники: src/components/README.md1-19 src/components/GUIDE_CREATE_FORM.md1-10

Резюме

Продвинутый рабочий процесс позволяет создавать пользовательские интерфейсы, когда 15 составных компонентов недостаточны:

Формы: Компонуйте Block + Box с пропом component для элементов форм, меток и полей ввода
Пользовательские виджеты: Используйте примитивы с семантическими пропами component и системой вариантов
Уникальные макеты: Компонуйте Grid, Flex, Stack для структурных требований
Гибридный подход: Комбинируйте пропы вариантов (~80% покрытие) с className для граничных случаев

Для стандартных сценариев с существующими компонентами используйте Базовый рабочий процесс. Для общих рекомендаций см. Лучшие практики. Источники: src/components/GUIDE_CREATE_FORM.md341-347 .devin/wiki.json191-198

Getting started

Architecture

Components

Development Guide

Продвинутый рабочий процесс

Продвинутый рабочий процесс

Цель и область применения

Когда использовать продвинутый рабочий процесс

Построение форм с помощью Block и Box

Паттерн пропа component

Паттерн структуры формы

Паттерны полей ввода

Поля Textarea

Полный пример формы

Многоколоночный макет формы

Паттерн валидации формы

Доступные пропы вариантов для примитивов

Варианты расстояний

Варианты макета

Варианты границ и стиля

Варианты цвета

Лучшие практики для продвинутой компоновки

Рекомендации для полей формы

Гибридный паттерн Вариант + className

Пользовательская компоновка компонентов

Создание переиспользуемых композитов

Нестандартные пользовательские сценарии, не связанные с формами

Сравнение: Базовый vs Продвинутый рабочий процесс

Резюме

Getting started

Architecture

Components

Development Guide

​Продвинутый рабочий процесс

​Цель и область применения

​Когда использовать продвинутый рабочий процесс

​Построение форм с помощью Block и Box

​Паттерн пропа component

​Паттерн структуры формы

​Паттерны полей ввода

​Поля Textarea

​Полный пример формы

​Многоколоночный макет формы

​Паттерн валидации формы

​Доступные пропы вариантов для примитивов

​Варианты расстояний

​Варианты макета

​Варианты границ и стиля

​Варианты цвета

​Лучшие практики для продвинутой компоновки

​Рекомендации для полей формы

​Гибридный паттерн Вариант + className

​Пользовательская компоновка компонентов

​Создание переиспользуемых композитов

​Нестандартные пользовательские сценарии, не связанные с формами

​Сравнение: Базовый vs Продвинутый рабочий процесс

​Резюме

Продвинутый рабочий процесс

Цель и область применения

Когда использовать продвинутый рабочий процесс

Построение форм с помощью Block и Box

Паттерн пропа component

Паттерн структуры формы

Паттерны полей ввода

Поля Textarea

Полный пример формы

Многоколоночный макет формы

Паттерн валидации формы

Доступные пропы вариантов для примитивов

Варианты расстояний

Варианты макета

Варианты границ и стиля

Варианты цвета

Лучшие практики для продвинутой компоновки

Рекомендации для полей формы

Гибридный паттерн Вариант + className

Пользовательская компоновка компонентов

Создание переиспользуемых композитов

Нестандартные пользовательские сценарии, не связанные с формами

Сравнение: Базовый vs Продвинутый рабочий процесс

Резюме