> ## Documentation Index > Fetch the complete documentation index at: https://ui8kit.buildy.tw/llms.txt > Use this file to discover all available pages before exploring further. # Базовые компоненты архитектура > UI8Kit Core фундаментальные примитивы - Block, Box, Grid, Flex и Stack компоненты, формирующие основу трехуровневой архитектуры # Базовые компоненты ## Цель и область применения Этот документ охватывает пять основополагающих примитивов в Слое 1 архитектуры: `Block`, `Box`, `Grid`, `Flex` и `Stack`. Эти компоненты служат строительными блоками для всех компонентов UI и макетов более высокого уровня в библиотеке. Они предоставляют прямой доступ к системе вариантов CVA и реализуют фундаментальные паттерны React, включая `forwardRef`, композицию типов TypeScript и пересылку HTML-атрибутов. Для документации по составным компонентам, расширяющим эти примитивы (Button, Card и др.), см. [UI-компоненты](#3.3). Для подробностей о системе вариантов см. [Система вариантов](#3.2). **Источники:** [README.md81-103](https://github.com/ui8kit/core/blob/2afe2195/README.md#L81-L103) [.devin/wiki.json56-63](https://github.com/ui8kit/core/blob/2afe2195/.devin/wiki.json#L56-L63) *** ## Архитектурная роль Базовые компоненты формируют основу трехслойной архитектуры. Они являются единственными компонентами, которые напрямую применяют систему вариантов CVA и рендерят семантические HTML5-элементы. Все компоненты Слоя 2 (UI-компоненты) и Слоя 3 (Макеты) в конечном итоге компонуют или расширяют эти пять примитивов. ``` Вывод Паттерны React Система вариантов CVA Слой 1: Базовые компоненты (этот документ) Block component='section' | 'article' | 'nav' | и т.д. data-class='block' Box component='div' | 'span' | любой ElementType data-class='box' Grid CSS Grid макет props: cols, rows, gap Flex Flexbox макет props: direction, align, justify Stack Вертикальное/горизонтальное расположение props: gap, direction class-variance-authority Разрешение вариантов spacingVariants() p, m, px, py и т.д. colorVariants() bg, c, borderColor layoutVariants() w, h, minH, position roundedVariants() rounded shadowVariants() shadow borderVariants() border, borderTop и т.д. forwardRef() Пересылка ref в DOM Интерфейсы TypeScript HTMLAttributes + VariantProps ...props Пересылка HTML-атрибутов Семантический HTML5 section, article, nav, header, footer Атрибуты data-class для обращения к DOM Классы Tailwind CSS применяются к className ``` **Источники:** [README.md62-103](https://github.com/ui8kit/core/blob/2afe2195/README.md#L62-L103) [src/components/ui/Block/Block.tsx1-88](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Block/Block.tsx#L1-L88) *** ## Пять основных примитивов ### Обзорная таблица | Компонент | Основное назначение | Поддержка семантического HTML | Ключевые варианты | Ширина по умолчанию | | - | - | - | - | - | | `Block` | Семантические блочные контейнеры | section, article, nav, header, footer, aside, main, div | spacing, color, layout, rounded, shadow, border | `w='full'` | | `Box` | Универсальный гибкий контейнер | Любой `ElementType` (div, span, p и т.д.) | spacing, color, layout | Нет по умолчанию | | `Grid` | Макеты CSS Grid | div с `display: grid` | spacing, layout, cols, rows, gap | Нет по умолчанию | | `Flex` | Макеты Flexbox | div с `display: flex` | spacing, layout, direction, align, justify | Нет по умолчанию | | `Stack` | Вертикальное/горизонтальное расположение | div с flexbox-расположением | spacing, gap, direction | Нет по умолчанию | **Источники:** [README.md81-103](https://github.com/ui8kit/core/blob/2afe2195/README.md#L81-L103) *** ## Фундаментальные паттерны React ### Реализация forwardRef Все базовые компоненты реализуют `forwardRef` для предоставления ссылки на базовый DOM-элемент родительским компонентам. Это позволяет выполнять императивные операции с DOM и интегрироваться со сторонними библиотеками. ``` ref={blockRef} пересылка ref blockRef.current?.scrollIntoView() Родительский компонент const blockRef = useRef(null) Block forwardRef DOM-элемент section | article | nav | и т.д. ``` **Пример структуры из компонента Block:** [src/components/ui/Block/Block.tsx33-36](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Block/Block.tsx#L33-L36) ``` export const Block = forwardRef(   ({ children, className, component, variant = 'div', ...props }, ref) => {     // Реализация компонента   } ); ``` **Источники:** [src/components/ui/Block/Block.tsx33-86](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Block/Block.tsx#L33-L86) ### Композиция типов TypeScript Базовые компоненты компонуют множество интерфейсов TypeScript для достижения типобезопасности между HTML-атрибутами, пропсами вариантов и кастомными пропсами компонента. ``` extends extends extends Pick<..., 'w' | 'h' | 'minH' | 'position'> extends extends extends включает BlockProps Интерфейс компонента React.HTMLAttributes Стандартные HTML-атрибуты VariantSpacingProps p, px, py, pt, pb, pl, pr m, mx, my, mt, mb, ml, mr ColorProps bg, c, borderColor VariantLayoutProps w, h, minH, maxW, position RoundedProps rounded ShadowProps shadow BorderProps border, borderTop и т.д. Кастомные пропсы children: ReactNode component?: ElementType variant?: 'section' | 'article' | ... ``` **Паттерн композиции типов из Block:** [src/components/ui/Block/Block.tsx20-31](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Block/Block.tsx#L20-L31) ``` export interface BlockProps    extends React.HTMLAttributes,     VariantSpacingProps,     ColorProps,     Pick,     RoundedProps,     ShadowProps,     BorderProps {   children: ReactNode;   component?: ElementType;   variant?: 'section' | 'main' | 'nav' | 'article' | 'header' | 'footer' | 'aside' | 'div'; } ``` **Источники:** [src/components/ui/Block/Block.tsx20-31](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Block/Block.tsx#L20-L31) ### Деструктуризация пропсов и пересылка HTML-атрибутов Базовые компоненты явно деструктурируют пропсы вариантов и пересылают оставшиеся HTML-атрибуты в базовый DOM-элемент, используя оператор spread (`...props`). ``` Входящие пропсы p='lg', onClick, data-testid и т.д. Деструктурированные пропсы вариантов p, px, py, m, bg, c, w, h, rounded, shadow, border Остальные пропсы (...props) onClick, data-testid, aria-label и т.д. Функции вариантов spacingVariants({ p, px, py, ... }) colorVariants({ bg, c }) layoutVariants({ w, h }) prop className cn(варианты, кастомный className) Базовый компонент Block/Box/Grid/Flex/Stack Отрендеренный DOM-элемент с className + ...props ``` **Паттерн деструктуризации пропсов из Block:** [src/components/ui/Block/Block.tsx34-61](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Block/Block.tsx#L34-L61) ``` ({    children,    className,   component,   variant = 'div',   // Пропсы отступов   p, px, py, pt, pb, pl, pr,   m, mx, my, mt, mb, ml, mr,   // Пропсы цвета   bg, c, borderColor,   // Пропсы макета   w = 'full', h, minH, position,   // Визуальные пропсы   rounded, shadow,   // Пропсы границ   border, borderTop, borderBottom, borderLeft, borderRight,   ...props  // Оставшиеся HTML-атрибуты }, ref) ``` **Источники:** [src/components/ui/Block/Block.tsx34-86](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Block/Block.tsx#L34-L86) *** ## Специфичные возможности компонентов ### Block: семантический HTML-контейнер `Block` разработан для семантических блочных элементов. По умолчанию имеет `w='full'` (полная ширина) и предоставляет проп `variant` для выбора семантических HTML5-элементов. **Ключевые характеристики:** * Выбор семантического элемента через проп `variant` * Полная ширина по умолчанию (`w='full'`) * Поддерживает все варианты spacing, color, layout, rounded, shadow и border * Использует `data-class="block"` для обращения к DOM **Разрешение типа элемента:** [src/components/ui/Block/Block.tsx62-68](https://github.com/ui8kit/core/blob/2afe2195/src/components/ui/Block/Block.tsx#L62-L68) ``` // Использовать variant как component, если component не указан явно const elementType = component || variant; return (    с полной шириной   Содержимое секции // Рендерится как