380 lines
18 KiB
Markdown
380 lines
18 KiB
Markdown
# HDROPDOWN CANON
|
||
|
||
Документ фиксирует единый канон dropdown-окон NODE.DC.
|
||
|
||
Связанный техдолг:
|
||
- [plane-src/docs/technical-debts/dropdown-standardization-debt.md](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/docs/technical-debts/dropdown-standardization-debt.md)
|
||
|
||
Цель документа:
|
||
- убрать локальные самодельные реализации выпадающих окон
|
||
- перевести dropdown на переиспользуемые shared-компоненты
|
||
- зафиксировать единый контракт для trigger, portal, placement, стилей и поведения
|
||
- исключить повторение проблемы, когда соседние controls работают по-разному на одном и том же экране
|
||
|
||
## Базовый принцип
|
||
|
||
Dropdown в системе не является "локальной маленькой версткой рядом с кнопкой".
|
||
|
||
Dropdown это:
|
||
- отдельный floating-layer
|
||
- отдельный reusable UI-компонент
|
||
- предсказуемый контракт открытия и закрытия
|
||
- единый визуальный канон
|
||
|
||
Если на экране есть несколько выпадающих окон, пользователь не должен видеть разные механики:
|
||
- одно окно открывается по тексту
|
||
- второе только по стрелке
|
||
- третье клипается контейнером
|
||
- четвертое открывается с другим типом привязки
|
||
|
||
Это считается дефектом стандартизации.
|
||
|
||
## Какие dropdown бывают
|
||
|
||
В проекте фиксируются три типа выпадающих окон.
|
||
|
||
### 1. Selection dropdown
|
||
|
||
Используется там, где пользователь выбирает значение.
|
||
|
||
Примеры:
|
||
- `Статус`
|
||
- `Приоритет`
|
||
- `Дата`
|
||
- `Назначенные`
|
||
- `Метки`
|
||
- выбор проекта
|
||
- выбор модуля
|
||
|
||
Смысл:
|
||
- пользователь выбирает одно или несколько значений
|
||
- у dropdown есть список опций
|
||
- часто есть поиск
|
||
- текущее значение отображается в trigger
|
||
|
||
Канонические reference-реализации:
|
||
- [state/base.tsx](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/apps/web/core/components/dropdowns/state/base.tsx:45)
|
||
- [priority.tsx](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/apps/web/core/components/dropdowns/priority.tsx:298)
|
||
|
||
### 2. Action dropdown
|
||
|
||
Используется там, где пользователь вызывает набор действий.
|
||
|
||
Примеры:
|
||
- `...` на карточке задачи
|
||
- `...` в detail-header
|
||
- быстрые действия у рабочего элемента
|
||
|
||
Смысл:
|
||
- dropdown не меняет поле напрямую
|
||
- dropdown показывает список команд
|
||
- каждая строка запускает `action`
|
||
|
||
Канонический shared-компонент:
|
||
- [action-dropdown.tsx](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/packages/ui/src/dropdowns/action-dropdown.tsx:109)
|
||
|
||
### 3. Context menu
|
||
|
||
Используется только как контекстное меню, а не как основной UI для кнопки `...`.
|
||
|
||
Примеры:
|
||
- правый клик
|
||
- context-actions, привязанные к `parentRef`
|
||
|
||
Правило:
|
||
- `ContextMenu` не заменяет основной dropdown по клику на кнопку
|
||
- если у карточки есть кнопка `...`, основной visible menu должен открываться через `ActionDropdown`
|
||
- `ContextMenu` допустим как дополнительный способ вызвать те же действия через right click
|
||
|
||
## Что запрещено
|
||
|
||
Запрещено делать новый dropdown через:
|
||
- локальный `isOpen` без shared-компонента
|
||
- локальный `useOutsideClick` внутри карточки
|
||
- inline absolute-блок внутри карточки
|
||
- popup, который живет внутри scroll-контейнера
|
||
- отдельную реализацию `...`, если рядом уже есть рабочий shared-dropdown
|
||
- другой trigger-контракт для соседних controls на одной оси
|
||
|
||
Запрещено:
|
||
- делать одну механику для `Статуса`, а другую для `...`
|
||
- открывать меню только по стрелке, если весь control должен быть кликабельным
|
||
- класть popup внутрь карточки, detail-pane, sidebar или sticky-header без portal
|
||
- компенсировать неверную архитектуру случайными `left/right translate`
|
||
|
||
## Главный стандарт переиспользования
|
||
|
||
Перед созданием нового dropdown нужно ответить только на два вопроса:
|
||
|
||
1. Это выбор значения или набор действий?
|
||
2. Есть ли уже shared-компонент для этого типа?
|
||
|
||
Если это выбор значения:
|
||
- использовать существующий selection-dropdown
|
||
- расширять existing base-component, а не писать новый popup с нуля
|
||
|
||
Если это список действий:
|
||
- использовать `ActionDropdown`
|
||
- не создавать отдельную локальную механику для карточки, detail-view или sidebar
|
||
|
||
## Канонический стек для dropdown
|
||
|
||
Любой новый dropdown должен опираться на один и тот же стек:
|
||
- реальный `trigger`
|
||
- `usePopper`
|
||
- `portal`
|
||
- `outside click close`
|
||
- `keyboard close/open`
|
||
- `preventOverflow`
|
||
- `flip`
|
||
|
||
Для action dropdown текущий канон зафиксирован в:
|
||
- [action-dropdown.tsx](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/packages/ui/src/dropdowns/action-dropdown.tsx:118)
|
||
|
||
Для selection dropdown reference-стек уже зафиксирован в:
|
||
- [state/base.tsx](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/apps/web/core/components/dropdowns/state/base.tsx:45)
|
||
|
||
## Trigger-правила
|
||
|
||
Trigger должен быть реальным интерактивным элементом.
|
||
|
||
Правила:
|
||
- dropdown привязывается к настоящей кнопке или surface-контролу
|
||
- нельзя заворачивать trigger в лишний интерактивный wrapper без причины
|
||
- нельзя делать `button` внутри `button`
|
||
- нельзя вешать отдельный click-interceptor на родительскую карточку так, чтобы он ломал trigger dropdown
|
||
|
||
Если control живет внутри кликабельной карточки:
|
||
- интерактивная зона обязана быть помечена как ignore-area для клика карточки
|
||
- карточка не должна перехватывать клик у dropdown trigger
|
||
|
||
Пример текущего канона для вложенной интерактивной зоны карточки:
|
||
- `data-control-link-ignore="true"`
|
||
|
||
## Portal-правила
|
||
|
||
Dropdown нельзя рендерить inline, если control находится внутри:
|
||
- карточки
|
||
- kanban-колонки
|
||
- list-item
|
||
- detail-pane
|
||
- sidebar
|
||
- properties section
|
||
- sticky toolbar
|
||
- scrollable container
|
||
|
||
В этих случаях popup обязан рендериться через portal на верхнем слое.
|
||
|
||
Базовое правило:
|
||
- `document.body` является стандартным portal target, если нет отдельного системного слоя
|
||
|
||
Причина:
|
||
- иначе будут клиппинг, неправильный z-index, обрезание соседними контейнерами и ложные оффсеты
|
||
|
||
## Placement-правила
|
||
|
||
Placement выбирается не "на глаз", а по канону control-type.
|
||
|
||
### Канон для selection dropdown
|
||
|
||
По умолчанию:
|
||
- `bottom-start`
|
||
|
||
Это уже используется соседними controls:
|
||
- `Статус`
|
||
- `Приоритет`
|
||
- `Дата`
|
||
|
||
### Канон для action dropdown карточек
|
||
|
||
Для quick-actions карточек используется тот же базовый anchor-канон, что и у соседних dropdown на той же верхней оси.
|
||
|
||
Текущая фиксация для kanban:
|
||
- [base-kanban-root.tsx](/Users/dcconstructions/Downloads/mnt/data/dc_taskmanager/NODEDC_TASKMANAGER/plane-src/apps/web/core/components/issues/issue-layouts/kanban/base-kanban-root.tsx:126)
|
||
- quick-actions в kanban теперь идут через `bottom-start`
|
||
|
||
Смысл:
|
||
- меню раскрывается относительно trigger по той же логике, что и соседние controls
|
||
- мы не подгоняем offset вручную под один экран
|
||
- мы нормализуем сам placement-contract
|
||
|
||
### Когда допустим другой placement
|
||
|
||
Другой placement допустим только если это диктует layout:
|
||
- `top-start`, если dropdown открывается из нижней части detail-pane и не должен врезаться в секцию ниже
|
||
- `top-end`, если control находится у правой кромки и popup иначе уходит за экран
|
||
|
||
Но это должно быть обосновано layout-контекстом, а не случайной визуальной подгонкой.
|
||
|
||
## Offset-правило
|
||
|
||
Offset нужен только для вертикального зазора между trigger и popup.
|
||
|
||
Канон:
|
||
- вертикальный gap небольшой и стабильный
|
||
- боковой offset по умолчанию не используется
|
||
|
||
Если кажется, что popup "смотрит не туда":
|
||
- сначала проверяется правильность `placement`
|
||
- потом anchor element
|
||
- и только в последнюю очередь ручной skidding
|
||
|
||
Правило:
|
||
- нельзя лечить неверный `placement` случайным `left/right offset`
|
||
|
||
## Визуальный канон
|
||
|
||
Все dropdown и popup подчиняются общему matte glass стилю.
|
||
|
||
Обязательные свойства:
|
||
- темный glass surface
|
||
- blur
|
||
- мягкая стеклянная граница
|
||
- без технических outline
|
||
- без браузерного синего focus ring
|
||
- без светлой инородной подложки на темном экране
|
||
|
||
Внутренние элементы dropdown:
|
||
- search shell визуально того же семейства, что и popup
|
||
- option row того же радиуса, что и системные popup-option
|
||
- hover мягкий, не кислотный
|
||
- active/selected state не ломает общую палитру
|
||
|
||
## Правила для списка действий
|
||
|
||
Action dropdown обязан принимать данные в виде menu items.
|
||
|
||
Каждый item:
|
||
- имеет `key`
|
||
- может иметь `icon`
|
||
- может иметь `title`
|
||
- может иметь `description`
|
||
- может иметь `disabled`
|
||
- может иметь `action`
|
||
|
||
Правило:
|
||
- визуальный рендер item делается внутри shared action-dropdown
|
||
- вызывающий код не рисует popup shell вручную
|
||
|
||
## Правила для карточек и detail-view
|
||
|
||
Для карточек рабочего элемента:
|
||
- `...` всегда action dropdown
|
||
- `Статус` и `Приоритет` всегда selection dropdown
|
||
- все три control-а на одной оси должны использовать совместимую trigger-геометрию и близкий placement-contract
|
||
|
||
Для detail-view:
|
||
- quick actions сверху не должны использовать отдельный popup-engine
|
||
- если действия те же, используется тот же `ActionDropdown`
|
||
|
||
Для `Внутреннего контура`:
|
||
- quick-actions карточек больше не живут на отдельной локальной механике
|
||
- они нормализуются под тот же shared dropdown-stack, что и другие controls
|
||
|
||
## Правила для хлебных крошек
|
||
|
||
Breadcrumb dropdown тоже подчиняется этому документу.
|
||
|
||
Правило:
|
||
- project breadcrumb это dropdown проектов
|
||
- module breadcrumb это dropdown модулей проекта
|
||
- весь breadcrumb-item кликабелен, а не только стрелка
|
||
- стрелка не может быть единственной интерактивной зоной
|
||
|
||
Если breadcrumb открывает список выбора:
|
||
- это selection dropdown
|
||
- trigger-контракт должен совпадать на всех проектных экранах
|
||
|
||
## Правила для новых экранов
|
||
|
||
Новый экран не имеет права изобретать свой тип dropdown, если:
|
||
- уже существует shared action dropdown
|
||
- уже существует shared selection dropdown
|
||
|
||
Порядок работы:
|
||
1. определить тип dropdown
|
||
2. выбрать shared-компонент
|
||
3. выбрать canonical placement
|
||
4. открыть popup через portal
|
||
5. применить glass-канон
|
||
6. проверить поведение внутри scroll/sticky/detail contexts
|
||
|
||
## Что делать, если нужен новый вариант
|
||
|
||
Если текущих shared-вариантов не хватает:
|
||
- сначала расширяется shared-component
|
||
- потом новый вариант документируется в этом файле
|
||
- только после этого он применяется на экранах
|
||
|
||
Что нельзя делать:
|
||
- сделать новый локальный dropdown "временно"
|
||
- спрятать временную логику внутри конкретной карточки
|
||
- оставлять два разных menu-engine для одинаковой задачи
|
||
|
||
## Legacy-правило
|
||
|
||
Если в проекте еще остались старые dropdown-механики:
|
||
- они считаются legacy
|
||
- новые карточечные quick-actions на них не строятся
|
||
- при доработке экрана предпочтение отдается переводу на shared-канон, а не лечению локального бага поверх legacy-кода
|
||
|
||
Это особенно касается:
|
||
- локальных `CustomMenu`-вариантов для карточечных `...`
|
||
- inline popup внутри карточек
|
||
- отдельных `isMenuActive` состояний в item-компонентах
|
||
|
||
## Reference-матрица переиспользования
|
||
|
||
Использовать:
|
||
|
||
- `ActionDropdown`
|
||
- для `...`
|
||
- для быстрых действий карточки
|
||
- для action-menu detail-header
|
||
|
||
- `StateDropdown`
|
||
- для выбора состояния
|
||
|
||
- `PriorityDropdown`
|
||
- для выбора приоритета
|
||
|
||
- `DateDropdown`
|
||
- для выбора даты
|
||
|
||
- `MemberDropdown`
|
||
- для выбора участников
|
||
|
||
- `ContextMenu`
|
||
- только как дополнительное context-menu по `parentRef`
|
||
- не как основной visible dropdown у кнопки `...`
|
||
|
||
## Минимальный check-list перед merge
|
||
|
||
Перед завершением задачи с dropdown надо проверить:
|
||
- popup открывается по клику на весь intended trigger
|
||
- popup не клипается родительским контейнером
|
||
- popup не уезжает за экран
|
||
- popup не живет на отдельном локальном menu-engine без причины
|
||
- `Статус / Приоритет / ...` на карточке не конфликтуют по click-handling
|
||
- карточка не перехватывает клик у trigger
|
||
- popup визуально соответствует matte glass канону
|
||
- hover, active и selected состояния выглядят как часть одной системы
|
||
|
||
## Канон внедрения
|
||
|
||
С этого момента правило простое:
|
||
|
||
- одинаковая задача = одинаковый dropdown-engine
|
||
- одинаковый control-type = одинаковый placement-contract
|
||
- одинаковый popup-type = одинаковый visual shell
|
||
|
||
Нельзя:
|
||
- лечить оффсет одного окна отдельной заплаткой
|
||
- оставлять соседние dropdown на разных механиках
|
||
- дублировать menu-логику в карточке, detail-pane и sidebar
|
||
|
||
Нужно:
|
||
- расширять shared-компонент
|
||
- переиспользовать его на всех экранах
|
||
- документировать новый вариант сразу в этом файле
|