NODEDC_TASKMANAGER/plane-src/docs/technical-debts/dropdown-standardization-debt.md

Dropdown Standardization Debt

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

Статус: active

Связанные документы:

• HDESIGN-CODE.md
• HDROPDOWN-CANON.md
• 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-компонент, а только потом меняется экран

Итоговое правило:

• редизайн делается поверх канона
• канон не ломается ради скорости редизайна