# Frontend Guide: Component Inventory

Этот документ отвечает на вопрос: какие UI-примитивы и повторно используемые компоненты уже есть в коде и когда их нужно брать вместо создания нового решения.

## 1. Foundation primitives

Это первый выбор для любого нового экрана.

### `frontend/src/app/globals.css`

Назначение:

- цветовые токены
- surface hierarchy
- базовые form primitives
- action states
- feedback states

Использовать, когда:

- нужен новый экран на существующей дизайн-системе
- нужно собрать карточку, поле, кнопку или feedback-блок без изобретения новой визуальной базы

Не использовать как:

- место для локального feature-хака без повторного применения

### `frontend/src/components/AppShell.tsx`

Что даёт:

- shell background
- header
- global search
- mobile navigation drawers
- `PageHeader`

Использовать, когда:

- нужен normal page внутри основного приложения

Не использовать, когда:

- экран является отдельным auth/legal flow и у него другой layout-contract

### `frontend/src/components/ui/Modal.tsx`

Что даёт:

- единый modal shell
- focus trap
- close handling
- header/footer contract
- responsive sizing

Использовать, когда:

- нужен обычный modal dialog
- нет отдельного сценария drawer/workspace/fullscreen flow

Не использовать как:

- основание для новой параллельной modal-системы

### `frontend/src/components/shared/SearchableSelect.tsx`

Компоненты:

- `SearchableSelectSingle`
- `SearchableSelectMulti`

Использовать, когда:

- нужен поиск по списку
- нужен multi-select
- нужно chip-представление выбранных значений
- нужен compose-like address field

Не использовать native `select`, если:

- начинаются локальные доработки стрелки
- нужен поиск
- нужен выбор нескольких пользователей

## 2. Shell-level и системные компоненты

### `NotificationCenter`

Роль:

- системный блок уведомлений

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

- в shell или system-level surface
- не как основу для произвольных выпадающих списков

### `MobileLeftDrawer` и `MobileCalendarDrawer`

Роль:

- мобильные системные drawer-паттерны

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

- для app-level mobile navigation / side panels

Не использовать:

- как shortcut для каждой произвольной feature-модалки

## 3. Feature-shared компоненты

Эти компоненты полезны как референс и иногда как основа для похожих сценариев, но они уже ближе к домену.

### Calendar

Файлы:

- `CalendarModal.tsx`
- `EventModal.tsx`
- `CalendarParticipantsModal.tsx`
- `CalendarSubscriptionsModal.tsx`
- `ViewDayEventsModal.tsx`
- `ViewEventDetailsModal.tsx`
- `calendar/CalendarSidebar.tsx`
- `calendar/CalendarCard.tsx`

Использовать как референс для:

- event forms
- side panels
- selection-heavy dialog flows

С оговоркой:

- calendar UI ещё не является эталоном всей системы и содержит legacy-решения

### Documents

Файлы:

- `DocumentDetailModal.tsx`
- `DocumentUploadForm.tsx`
- `DocumentPreview.tsx`
- `DocumentMetadataEditor.tsx`
- `DocumentComments.tsx`

Использовать как референс для:

- document-heavy UI
- detail panels
- upload flows
- metadata forms

С оговоркой:

- documents содержит заметный пласт legacy-геометрии и нуждается в дальнейшем выравнивании

### Requests

Файлы:

- `requests/RequestAttachmentPreviewModal.tsx`
- `requests/RequestAvatar.tsx`
- `requests/RequestComposeModal.tsx`
- `requests/RequestDetailModal.tsx`
- `requests/RequestListControls.tsx`
- `requests/RequestListItem.tsx`
- `requests/RequestListSection.tsx`
- `requests/RequestSwipeModePanel.tsx`
- `requests/RequestUserBadge.tsx`
- `requests/SwipeApprovalMode.tsx`
- `app/requests/page.tsx`
- `hooks/useRequestsPage.ts`
- `hooks/useRequestsPageScreen.ts`

Использовать как референс для:

- compose-like form pattern
- detail modal с participant-heavy content
- page-level toolbar/filter block, который вынесен из страницы в feature component
- feature container для list shell, который собирает rows + empty state + load more
- отдельный mode-panel для alternate flow вроде swipe-review
- attachment preview modal как отдельный feature block, а не хвост page-level JSX
- локальный avatar/media wrapper вокруг `next/image`, когда feature уже использует несколько однотипных аватаров и preview
- participant badge pattern для request-like доменов
- participant-only UI decisions
- conditional action rendering по данным API
- разделения page-level orchestration и feature-level compose workspace
- screen-specific router/menu/deep-link orchestration без засорения page-level JSX

`requests/RequestUserBadge.tsx` использовать как ориентир, когда нужен person-chip паттерн:

- `avatar + name` внутри capsule
- опциональная ссылка на профиль
- compact и large варианты внутри одного feature wrapper

Не копировать компонент дословно во все модули, но сохранять приоритет этого паттерна над сырой строкой получателя или локально собранным badge.

С оговоркой:

- `requests` сейчас хороший ориентир по декомпозиции и compose/detail flow, но не должен автоматически становиться visual-template для всех dense lists

### Users / profile-like screens

Файлы:

- `users/ProfileSections.tsx`
- `users/EditUserProfileModal.tsx`
- `users/EmployeeActionModal.tsx`
- `users/EmployeeActionsTimeline.tsx`
- `hooks/useProfilePage.ts`
- `hooks/useUserDetailPage.ts`

Использовать как референс для:

- profile hero
- profile sections
- info cards
- action timeline
- page-level profile controllers, которые держат loading/derived state/API orchestration вне page JSX

### Departments

Файлы:

- `departments/DepartmentPersonChip.tsx`
- `app/departments/[id]/page.tsx`
- `hooks/useDepartmentPage.ts`

Использовать как референс для:

- detail screen, который должен уметь переключаться между `showcase` и `management` без смены route и без ощущения двух разных страниц
- page-level controller для domain actions вокруг одного объекта: overview, members и inline management actions
- entry-point с detail page в уже существующий object-chat, когда объекту нужен access к реальной message history без локального duplicate UI
- richer detail layout, где есть сильный header и один основной roster/workspace-блок, без раздувания служебных summary-panels и вторичных management-panels
- member roster с role assignment и person-chip подачей вместо сырых строк участников
- role management на уровне названий ролей и назначений участникам, встроенный в roster, без фронтового permission-editor

С оговоркой:

- `departments/[id]` должен оставаться привязанным к реальным backend-capabilities; если у отдела уже есть живой object-chat, не дублировать его локальной discussion-панелью на странице

### Messages

Файлы:

- `messages/MessageComposer.tsx`
- `messages/ChatMessageItem.tsx`
- `messages/ChatDialogHeader.tsx`
- `ScrollableMessageList.tsx`

Использовать как референс для:

- dense interactive lists
- composer area
- dialog-like chat surface

С оговоркой:

- chat решает очень специфический UX, поэтому не должен автоматически становиться шаблоном для остальных модулей

## 4. Что считать shared, а что нет

Компонент нужно считать shared, если:

- он решает повторяемую визуальную механику
- у него нет жёсткой доменной привязки
- он пригоден минимум для двух feature-зон

Компонент не нужно тащить в shared, если:

- он глубоко привязан к одному домену
- у него много domain-specific props и состояний
- он служит хорошим референсом, но плохим универсальным primitive

## 5. Быстрый выбор перед новой разработкой

Если нужен:

- page shell: `AppShell`, `PageHeader`
- modal: `Modal`
- searchable dropdown: `SearchableSelect*`
- compose address line: `SearchableSelectMulti` с compose-like layout
- comment composer / delete action: `shared/CommentControls.tsx`
- primary/secondary surface: `app-surface` / `app-surface-muted`
- feedback block: `app-selected`, `app-feedback-*`

Если после этого всё ещё хочется создать новый primitive, сначала проверить:

- нет ли уже похожего решения в `components`
- нельзя ли расширить существующий shared-компонент
- не пытаемся ли мы решить локальную проблему новым глобальным паттерном