# Dropdown Standardization Debt

Дата фиксации: `2026-04-22`

Статус: `active`

Связанные документы:
- [HDESIGN-CODE.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/HDESIGN-CODE.md)
- [HDROPDOWN-CANON.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/HDROPDOWN-CANON.md)
- [HUI-CANON-AUDIT.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/HUI-CANON-AUDIT.md)

## Зачем фиксируется этот техдолг

В проекте уже выполнена большая часть канонизации dropdown-окон, но этап еще не завершен.

Это означает:
- общий контракт для dropdown уже определен
- значимая часть экранов уже переведена на shared-компоненты
- legacy-механики еще не вычищены полностью
- визуальный слой новых dropdown и связанных элементов еще не доведен на всех экранах до одного и того же дизайн-эталона

Этот документ нужен, чтобы:
- не потерять текущий контекст миграции
- не откатиться обратно к локальным menu-wrapper решениям
- иметь единый технический ориентир перед следующим большим этапом редизайна
- отделить архитектурную канонизацию dropdown-stack от визуальной доводки экранов

## Что уже считается сделанным

На текущем этапе уже зафиксированы и частично внедрены следующие принципы:

### 1. Типизация dropdown по смыслу

В системе признаются только три вида выпадающих окон:
- `Selection dropdown`
- `Action dropdown`
- `Context menu`

Правило:
- если пользователь выбирает значение, используется `SelectionDropdown`
- если пользователь вызывает список действий, используется `ActionDropdown`
- `ContextMenu` допустим только как secondary/right-click механизм

### 2. Общий канон поведения

Dropdown больше не считается локальной версткой рядом с кнопкой.

Dropdown должен быть:
- отдельным floating-layer
- привязанным к реальному trigger-элементу
- открываемым через общий popper/portal стек
- одинаковым по контракту открытия, закрытия и позиционирования

### 3. Уже мигрированные слои

На общий канон уже переведены крупные блоки:
- project/module breadcrumbs
- quick-actions карточек и detail action-menu
- desktop header action-menu
- desktop sorting dropdown
- mobile selection/menu слой для части экранов
- searchable select-пикеры
- form/settings select-пикеры

### 4. Уже определен визуальный канон

Для dropdown зафиксирован matte black glass подход:
- темный glass surface
- blur
- мягкая граница
- единый popup-shell
- единый ритм option-row
- запрет на случайные outline, clip и локальные подложки

## В чем состоит незакрытый долг

Долг не в том, что dropdown “вообще не стандартизированы”.

Долг в том, что стандартизация завершена не до конца на уровне всей системы.

Проблема сейчас состоит из четырех частей.

### 1. Не все legacy dropdown переведены на shared-канон

В проекте еще остаются места, где используются старые механики:
- `CustomMenu`
- `CustomSelect`
- `CustomSearchSelect`
- локальные menu-wrapper решения вокруг существующих control-компонентов

Это критично, потому что:
- соседние controls могут вести себя по-разному на одном экране
- фиксы начинают делаться точечно, а не системно
- новая UI-логика начинает разъезжаться по разным слоям

### 2. Не все dropdown доведены до одной и той же схемы переиспользования

Даже там, где поведение уже близко к канону, еще встречаются расхождения:
- разные trigger-shell
- разные popup-wrapper
- разная схема option-render
- разные локальные классы для похожих dropdown

Это опасно тем, что код выглядит “уже почти каноничным”, но реально еще не является одним и тем же reusable-механизмом.

### 3. Визуальный канон еще не протянут через все экраны

Архитектурный слой во многих местах уже выровнен, но визуально часть экранов еще живет на смешанном состоянии:
- popup уже новый, а surrounding layout еще старый
- dropdown уже каноничный, а рядом карточка, detail-pane или modal сверстаны по старому ритму
- glass shell и spacing формально есть, но не совпадают с эталоном `Внутреннего контура`

### 4. Нет финального закрытия этапа по критерию Definition of Done

Этап можно считать закрытым только тогда, когда:
- legacy dropdown-механики перестают быть обязательным рабочим слоем
- новые экраны не изобретают свои popup-решения
- существующие экраны используют только зафиксированные shared-компоненты
- UI доведен до одного и того же канона не только функционально, но и визуально

Сейчас этот критерий еще не выполнен.

## Что запрещено до полного закрытия долга

До закрытия этого техдолга запрещено:
- добавлять новый dropdown через локальный `isOpen` и `absolute` popup
- делать новый `...` через отдельный компонент, если уже есть `ActionDropdown`
- использовать `CustomMenu` как “быструю временную затычку” для нового action-menu
- использовать `CustomSelect` или `CustomSearchSelect` для новых экранов, если их можно закрыть каноничными shared-компонентами
- лечить проблемы positioning случайными `left/right translate` без исправления placement-контракта
- исправлять визуальный разнобой только внешней оберткой, если проблема находится внутри базового reusable-компонента

## Что обязательно делать при продолжении этапа

Любая новая работа по dropdown и связанным UI-элементам должна идти в таком порядке:

1. Определить тип dropdown:
   `selection`, `action` или `context`.
2. Проверить, есть ли shared-компонент для этого сценария.
3. Если shared-компонент есть:
   дорабатывать его, а не создавать новый локальный wrapper.
4. Если shared-компонент не покрывает кейс полностью:
   расширять shared-контракт, чтобы изменение переиспользовалось и на других экранах.
5. После архитектурного изменения дотягивать экран до дизайн-канона целиком, а не только dropdown.

## Граница между архитектурой и редизайном

Важно разделять два разных этапа.

### Текущий этап

Это этап архитектурной канонизации dropdown-layer.

Его задача:
- вычистить legacy popup-механики
- выровнять trigger/popup/portal/placement слой
- свести похожие выпадающие окна к одним и тем же shared-компонентам

### Следующий большой этап

Это этап редизайна UI-элементов под новые каноны.

Его задача:
- пройтись по живым экранам проекта
- довести карточки, detail-pane, filters, modal, toolbar и list layouts до одного визуального эталона
- использовать уже зафиксированный dropdown-канон как инфраструктурную основу, а не спорить заново о popup-поведении

Именно этот второй этап теперь считается более приоритетным.

## Какие области еще требуют возврата

На момент фиксации документа к этапу нужно вернуться минимум по следующим направлениям:

### 1. Legacy select/search layer

Нужно дочистить остатки старых select-механик:
- `automation`
- `export`
- `pages modal`
- `api-token`
- `publish-project`
- `rich-filters`

Цель:
- убрать остаточные прямые зависимости от legacy select/search dropdown-слоя
- завершить переход на `SelectionDropdown` и `SearchSelectionDropdown`

### 2. Legacy action/context layer

Нужно проверить, не остались ли вторичные места, где visible action-menu еще живет на старом menu-engine.

Цель:
- не допустить, чтобы `ActionDropdown` существовал как “еще один способ”
- закрепить его как основной стандарт для action popup

### 3. Экранный визуальный проход

Нужно отдельно пройтись по:
- `Внутреннему контуру`
- `Внешним контурам`
- `Предложениям`
- `Модулям`
- `Циклам`
- `Видам`
- `Страницам`
- workspace/sidebar/settings flows

Цель:
- довести не только сами dropdown, но и surrounding UI до общего дизайн-ритма

## Признак завершения техдолга

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

- на новых экранах больше не появляются локальные dropdown-механики
- legacy `CustomMenu` не используется как основной visible action dropdown
- legacy `CustomSelect` и `CustomSearchSelect` перестают быть рабочим стандартом для новых задач
- общие shared dropdown покрывают реальные product-сценарии без точечных обходов
- визуально dropdown, filters, action menu и related cards/modals подчиняются одному и тому же канону
- команда может вернуться к экрану через несколько недель и продолжить работу без повторного архитектурного переизобретения

## Что делать перед стартом большого этапа редизайна

Перед стартом следующего большого этапа нужно считать зафиксированными следующие вводные:

- dropdown-канон уже существует и описан
- техдолг по миграции еще активен
- редизайн не должен плодить новые popup-механики
- если при редизайне находится dropdown-кейс, которого нет в shared-компонентах, сначала расширяется shared-компонент, а только потом меняется экран

Итоговое правило:
- редизайн делается поверх канона
- канон не ломается ради скорости редизайна