> ## 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 - централизованный каталог метаданных, обеспечивающий множественные паттерны установки и использования

# Реестр компонентов

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

Реестр компонентов — это централизованная система метаданных, которая каталогизирует все компоненты в `@ui8kit/core` и обеспечивает несколько паттернов установки и использования. Реестр определен в [src/registry.json1-281](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L1-L281) и предоставляет структурированные метаданные, включая названия компонентов, типы, зависимости, пути к файлам и целевые директории.

Эта страница документирует формат реестра, схему метаданных компонентов, процесс регистрации и то, как реестр поддерживает различные методы установки. Для получения информации о конвейере сборки, который генерирует артефакты реестра, см. [Система сборки](#3.6). Для получения подробной информации о распространении пакета см. [Структура пакета](#3.5).

**Источники:** [src/registry.json1-281](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L1-L281) [README.md251-276](https://github.com/ui8kit/core/blob/2afe2195/README.md#L251-L276)

***

## Структура файла реестра

Реестр представляет собой JSON-файл, соответствующий схеме buildy-ui. Он содержит три свойства верхнего уровня:

| Свойство | Тип | Описание |
| - | - | - |
| `$schema` | string | URL JSON-схемы для валидации |
| `items` | array | Массив объектов метаданных компонентов |
| `version` | string | Версия схемы реестра (в настоящее время "1.0.0") |
| `lastUpdated` | string | Временная метка последнего обновления в формате ISO 8601 |
| `registry` | string | Идентификатор реестра ("ui") |

**Источники:** [src/registry.json2-281](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L2-L281)

### Диаграмма схемы реестра

```
registry.json

$schema: buildy.tw/schema/registry.json

items[]
Массив метаданных компонентов

version: 1.0.0

lastUpdated: временная метка ISO 8601

registry: ui

Объект метаданных компонента

name: string

type: registry:ui | registry:layout

description: string

dependencies: string[]

devDependencies: string[]

files[]

path: путь источника

target: целевая директория
```

**Источники:** [src/registry.json2-10](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L2-L10) [src/registry.json278-281](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L278-L281)

***

## Схема метаданных компонента

Каждая запись компонента в массиве `items` содержит следующие поля:

| Поле | Тип | Обязательное | Описание |
| - | - | - | - |
| `name` | string | Да | Название компонента (например, "Button", "Card") |
| `type` | string | Да | Категория компонента: "registry:ui" или "registry:layout" |
| `description` | string | Да | Описание компонента (может быть пустой строкой) |
| `dependencies` | string\[] | Да | Зависимости времени выполнения (например, "react", "lucide-react") |
| `devDependencies` | string\[] | Да | Зависимости разработки (обычно пустой массив) |
| `files` | object\[] | Да | Массив объектов метаданных файлов |
| `files[].path` | string | Да | Путь к исходному файлу относительно корня репозитория |
| `files[].target` | string | Да | Целевая директория в проекте потребителя |

**Источники:** [src/registry.json4-17](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L4-L17)

### Распределение типов компонентов

Реестр содержит 18 компонентов двух типов:

| Тип | Количество | Компоненты |
| - | - | - |
| `registry:ui` | 15 | Title, Text, Stack, Sheet, Image, Icon, Group, Grid, Container, Card, Button, Box, Block, Badge, Accordion |
| `registry:layout` | 3 | SplitBlock, LayoutBlock, DashLayout |

**Источники:** [src/registry.json2-276](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L2-L276)

### Пример записи компонента

Компонент Button демонстрирует минимальную запись реестра:

```
{
  "name": "Button",
  "type": "registry:ui",
  "description": "",
  "dependencies": ["react"],
  "devDependencies": [],
  "files": [
    {
      "path": "src/components/ui/Button/Button.tsx",
      "target": "components/ui"
    }
  ]
}
```

**Источники:** [src/registry.json156-169](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L156-L169)

***

## Классификация зависимостей

Реестр отслеживает две категории зависимостей для каждого компонента:

### Зависимости времени выполнения

Компоненты объявляют зависимости времени выполнения, которые должны быть установлены в приложении потребителя:

| Зависимость | Используется в | Назначение |
| - | - | - |
| `react` | Все компоненты | Основная библиотека React |
| `lucide-react` | Sheet, Accordion | Компоненты иконок (ChevronRight, X) |
| `react-resizable-panels` | DashLayout | Система макета с изменяемыми панелями |

**Примечание:** `class-variance-authority`, `clsx` и `tailwind-merge` являются зависимостями уровня пакета, определенными в [package.json48-53](https://github.com/ui8kit/core/blob/2afe2195/package.json#L48-L53) и не отслеживаются для каждого компонента.

### Зависимости разработки

Массив `devDependencies` присутствует во всех записях, но обычно пуст, поскольку зависимости разработки управляются на уровне пакета в [package.json59-66](https://github.com/ui8kit/core/blob/2afe2195/package.json#L59-L66)

**Источники:** [src/registry.json8-10](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L8-L10) [src/registry.json54-56](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L54-L56) [src/registry.json266-268](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L266-L268) [package.json48-53](https://github.com/ui8kit/core/blob/2afe2195/package.json#L48-L53)

***

## Сопоставление путей к файлам

Каждая запись компонента сопоставляет исходные файлы с целевыми директориями в проекте потребителя:

### Структура целевых директорий

| Целевая директория | Назначение | Компоненты |
| - | - | - |
| `components/ui` | UI-компоненты | 15 компонентов (Button, Card и т.д.) |
| `layouts` | Шаблоны макетов | 3 компонента (DashLayout, LayoutBlock, SplitBlock) |

### Диаграмма сопоставления файлов

```
Проект потребителя

Метаданные реестра

Исходный репозиторий

src/components/ui/Button/Button.tsx

src/layouts/DashLayout.tsx

Запись Button
path: src/components/ui/Button/Button.tsx
target: components/ui

Запись DashLayout
path: src/layouts/DashLayout.tsx
target: layouts

components/ui/Button.tsx

layouts/DashLayout.tsx
```

**Источники:** [src/registry.json14-16](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L14-L16) [src/registry.json240-243](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L240-L243) [src/registry.json272-274](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L272-L274)

***

## Генерация реестра

Реестр генерируется и поддерживается с помощью инструмента CLI `buildy-ui`:

### Команда Scan

Скрипт `scan` в [package.json26](https://github.com/ui8kit/core/blob/2afe2195/package.json#L26-L26) выполняет сканер buildy-ui:

```
bunx buildy-ui@latest scan
```

Эта команда:

1. Сканирует директории компонентов (`src/components/ui/`, `src/layouts/`)
2. Извлекает метаданные компонентов из исходных файлов
3. Определяет зависимости путем анализа импортов
4. Обновляет [src/registry.json1-281](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L1-L281) текущими метаданными
5. Устанавливает временную метку `lastUpdated` на текущее время ISO 8601

**Источники:** [package.json26](https://github.com/ui8kit/core/blob/2afe2195/package.json#L26-L26) [src/registry.json279](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L279-L279)

### Команда Build Registry

Скрипт `build:r` в [package.json27](https://github.com/ui8kit/core/blob/2afe2195/package.json#L27-L27) генерирует артефакты для распространения:

```
bunx buildy-ui@latest build
```

Это создает опубликованный пакет реестра в `packages/registry/` для программного доступа.

**Источники:** [package.json27-28](https://github.com/ui8kit/core/blob/2afe2195/package.json#L27-L28)

***

## Интеграция с методами установки

Реестр поддерживает четыре различных паттерна установки:

### Сравнение методов установки

| Метод | Команда | Использование реестра | Случай использования |
| - | - | - | - |
| Полная библиотека | `npm install @ui8kit/core` | Не используется (устанавливает весь пакет) | Комплексные проекты |
| По компонентам | `npx buildy-ui add button` | Читает метаданные для выборочной установки | Оптимизация бандла |
| Программный доступ | `import registry from 'registry.json'` | Прямой доступ к JSON | Инструменты/автоматизация |
| Git Submodule | `git submodule add` | Не используется (клонирует исходники) | Архитектуры монорепозитория |

**Источники:** [README.md255-276](https://github.com/ui8kit/core/blob/2afe2195/README.md#L255-L276)

### Поток установки по компонентам

```
Отсутствует

Присутствует

npx buildy-ui add button

src/registry.json

Поиск 'button' в массиве items

Извлечение метаданных:
name: Button
type: registry:ui
files: src/components/ui/Button/Button.tsx
dependencies: react

Получение файла с GitHub:
ui8kit/core/src/components/ui/Button/Button.tsx

Проверка зависимостей:
Установлен ли react?

Установка отсутствующих зависимостей:
npm install react

Запись в целевую директорию:
components/ui/Button.tsx

Установка завершена
```

**Источники:** [README.md261-265](https://github.com/ui8kit/core/blob/2afe2195/README.md#L261-L265) [src/registry.json156-169](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L156-L169)

***

## Программный доступ к реестру

Приложения могут импортировать JSON реестра для автоматизации и инструментов:

### Структура данных реестра

```
interface RegistryFile {
  $schema: string;
  items: ComponentItem[];
  version: string;
  lastUpdated: string;
  registry: string;
}

interface ComponentItem {
  name: string;
  type: "registry:ui" | "registry:layout";
  description: string;
  dependencies: string[];
  devDependencies: string[];
  files: FileItem[];
}

interface FileItem {
  path: string;
  target: string;
}
```

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

```
import registry from '@ui8kit/core/registry.json';

// Список всех UI-компонентов
const uiComponents = registry.items
  .filter(item => item.type === 'registry:ui')
  .map(item => item.name);

// Поиск компонентов, требующих lucide-react
const iconComponents = registry.items
  .filter(item => item.dependencies.includes('lucide-react'))
  .map(item => item.name);
// Результат: ["Sheet", "Accordion"]

// Получение целевых директорий установки
const targets = [...new Set(
  registry.items.flatMap(item => 
    item.files.map(file => file.target)
  )
)];
// Результат: ["components/ui", "layouts"]
```

**Источники:** [README.md268-276](https://github.com/ui8kit/core/blob/2afe2195/README.md#L268-L276) [src/registry.json1-281](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L1-L281)

***

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

Реестр обеспечивает полное покрытие иерархии компонентов библиотеки:

### Инвентаризация компонентов по слоям

```
Слой 3: Макеты

Слой 2: UI-компоненты

Слой 1: Базовые примитивы

Записи реестра: всего 18

registry:ui
15 компонентов

registry:layout
3 компонента

Box
src/components/ui/Box/Box.tsx

Block
src/components/ui/Block/Block.tsx

Grid
src/components/ui/Grid/Grid.tsx

Stack
src/components/ui/Stack/Stack.tsx

Button
src/components/ui/Button/Button.tsx

Card
src/components/ui/Card/Card.tsx

Text
src/components/ui/Text/Text.tsx

Title
src/components/ui/Title/Title.tsx

Container
src/components/ui/Container/Container.tsx

Icon
src/components/ui/Icon/Icon.tsx

Image
src/components/ui/Image/Image.tsx

Badge
src/components/ui/Badge/Badge.tsx

Group
src/components/ui/Group/Group.tsx

Sheet
src/components/ui/Sheet/Sheet.tsx

Accordion
src/components/ui/Accordion/Accordion.tsx

DashLayout
src/layouts/DashLayout.tsx

LayoutBlock
src/layouts/LayoutBlock.tsx

SplitBlock
src/layouts/SplitBlock.tsx
```

**Источники:** [src/registry.json1-276](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L1-L276)

***

## Обслуживание реестра

### Управление версиями

Реестр использует семантическое версионирование независимо от версии пакета:

* **Версия реестра:** [src/registry.json278](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L278-L278) - В настоящее время "1.0.0"
* **Версия пакета:** [package.json3](https://github.com/ui8kit/core/blob/2afe2195/package.json#L3-L3) - В настоящее время "0.1.8"

Версия реестра изменяется при изменении схемы метаданных, а не при добавлении или изменении компонентов.

### Временная метка последнего обновления

Поле `lastUpdated` в [src/registry.json279](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L279-L279) записывает время последнего изменения в виде строки ISO 8601:

```
"lastUpdated": "2025-10-30T13:21:21.408Z"
```

Эта временная метка обновляется автоматически при выполнении `npm run scan`.

**Источники:** [src/registry.json278-281](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L278-L281) [package.json3](https://github.com/ui8kit/core/blob/2afe2195/package.json#L3-L3) [package.json26](https://github.com/ui8kit/core/blob/2afe2195/package.json#L26-L26)

***

## Распространение реестра

Реестр распространяется через два канала:

### Распространение через NPM пакет

JSON реестра включен в NPM пакет через поле `files` в [package.json39-42](https://github.com/ui8kit/core/blob/2afe2195/package.json#L39-L42):

```
"files": [
  "dist/**/*",
  "README.md",
  "LICENSE"
]
```

Примечание: registry.json не указан явно здесь, но включен в NPM tarball для программного доступа.

### Отдельный пакет реестра

Скрипт `publish` в [package.json28](https://github.com/ui8kit/core/blob/2afe2195/package.json#L28-L28) публикует отдельный пакет реестра:

```
cd packages/registry && npm version patch && npm publish
```

Это создает отдельный NPM пакет, содержащий только метаданные реестра для облегченного доступа инструментами CLI.

**Источники:** [package.json28](https://github.com/ui8kit/core/blob/2afe2195/package.json#L28-L28) [package.json39-42](https://github.com/ui8kit/core/blob/2afe2195/package.json#L39-L42)

***

## Интеграция с конвейером сборки

Реестр взаимодействует с другими системами времени сборки:

```
Распространение

Артефакты сборки

Инструменты времени сборки

Исходные файлы

сканирует

генерирует

компилирует

генерирует

извлекает

генерирует

включен в

опубликован как

включен в

ссылается в

src/components/ui/**/.tsx
src/layouts/.tsx

buildy-ui scan

Компилятор TypeScript

Экстрактор CVA

src/registry.json

dist/

src/lib/core-classes.json

NPM пакет
@ui8kit/core

Пакет реестра
```

**Источники:** [package.json22-28](https://github.com/ui8kit/core/blob/2afe2195/package.json#L22-L28) [src/registry.json1-281](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L1-L281)

***

## Резюме

Реестр компонентов служит единым источником истины для метаданных компонентов в `@ui8kit/core`. Он обеспечивает:

1. **Установку по компонентам** через `npx buildy-ui add [component]`
2. **Программный доступ** для инструментов и автоматизации
3. **Отслеживание зависимостей** для выборочных установок
4. **Сопоставление путей к файлам** от источника к целевым директориям
5. **Классификацию компонентов** по типу (UI vs Layout)

Реестр автоматически поддерживается с помощью команды `buildy-ui scan` и распространяется через NPM вместе со скомпилированным пакетом.

**Источники:** [src/registry.json1-281](https://github.com/ui8kit/core/blob/2afe2195/src/registry.json#L1-L281) [README.md251-276](https://github.com/ui8kit/core/blob/2afe2195/README.md#L251-L276) [package.json26-28](https://github.com/ui8kit/core/blob/2afe2195/package.json#L26-L28)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.