87 lines
6.1 KiB
Markdown
87 lines
6.1 KiB
Markdown
# Earth Toolbar And Overlay Coordination
|
|
|
|
This document describes the current coordination rules between the Earth toolbar buttons and the search panel, settings modal, news/live panel, and layer panel. Use this matrix when changing interactions, adding buttons, or adjusting panels so one action does not close an unrelated overlay.
|
|
|
|
Related entries:
|
|
|
|
- [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
|
|
- [Frontend Layout Guidelines](/home/ray/dev/linkong/planet/docs/technical/en/frontend-layout-guidelines.md)
|
|
|
|
## Toolbar Button Directory
|
|
|
|
The toolbar is marked by `.earth-toolbar-btn` in [index.html](/home/ray/dev/linkong/planet/frontend/public/earth/index.html):
|
|
|
|
| ID | Title | Type | Overlay / action |
|
|
|----|-------|------|------------------|
|
|
| `layer-action` | Layers | Overlay toggle | HUD panel `layer-toggles` on desktop / mobile drawer `layers` card |
|
|
| `search-action` | Search | Overlay toggle | Search panel on desktop / mobile drawer `search` card |
|
|
| `rotate-toggle` | Auto rotate | Standalone toggle | No overlay |
|
|
| `toggle-tv` | News live | Overlay toggle | Media panel `media-panel` with TV and News tabs |
|
|
| `reload-data` | Reload data | Standalone action | No overlay |
|
|
| `zoom-trigger` | Zoom control | Floating menu | Zoom floating menu |
|
|
| `settings-trigger` | Settings | Overlay toggle | Settings modal on desktop / mobile drawer `settings` card |
|
|
| `reset-view` | Reset view | Standalone action | No overlay |
|
|
| `layout-toggle` | Maximize layout | Standalone toggle | No overlay |
|
|
|
|
## Shared Coordination Entry Point
|
|
|
|
[controls.js::closeTransientMobileOverlays](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js) is the shared coordinator for deciding what should close when an overlay opens.
|
|
|
|
Every path that opens a fullscreen-style overlay calls `closeTransientMobileOverlays({ except })`, where `except` names the overlay that should stay open:
|
|
|
|
```js
|
|
closeTransientMobileOverlays({ except: "search" });
|
|
closeTransientMobileOverlays({ except: "settings" });
|
|
closeTransientMobileOverlays({ except: "media" });
|
|
closeTransientMobileOverlays({ except: "layer-toggles" });
|
|
```
|
|
|
|
Current `except` values are `"search"`, `"settings"`, `"media"`, `"layer-toggles"`, or omitted to close all transient overlays.
|
|
|
|
## Close Matrix
|
|
|
|
`close` means the overlay closes; `keep` means it remains open.
|
|
|
|
| Action | Search | Settings | Mobile layers drawer | News/live |
|
|
|--------|:------:|:--------:|:--------------------:|:---------:|
|
|
| Open search (`except: "search"`) | self | close | close | keep |
|
|
| Open settings (`except: "settings"`) | close | self | close | keep |
|
|
| Open news/live (`except: "media"`) | close | close | close | self |
|
|
| Open mobile layers (`except: "layer-toggles"`) | close | close | self | close |
|
|
| Close all (`except: null`) | close | close | close | close |
|
|
|
|
Examples:
|
|
|
|
- Clicking toolbar Settings closes search and the mobile layer drawer, but keeps news/live open.
|
|
- Clicking toolbar Layers on mobile opens the `layers` drawer and closes search, settings, and news.
|
|
- Clicking News Live closes search, settings, and the layer drawer, then toggles the media panel.
|
|
|
|
## Design Rules
|
|
|
|
1. **Floating menus such as `zoom-trigger` are not overlays.** They use `bindFloatingMenu` and are managed separately by `closeFloatingMenus()`. Opening any overlay first closes floating menus.
|
|
2. **Desktop `layer-toggles` is a persistent HUD panel.** `closeTransientMobileOverlays` only closes it when `activeMobileDrawerId === "layer-toggles"`, so desktop search, settings, and news do not disturb the layer panel.
|
|
3. **News/live is independent from settings.** Users often adjust collector settings while watching news, so opening settings does not close the media panel. This became an invariant after the May 2026 coordination patch.
|
|
4. **Search and news are both primary information overlays.** Search opens without closing news, and news opens without closing search. If product direction changes, update both sides in `closeTransientMobileOverlays` so the matrix stays symmetric.
|
|
5. **Mobile drawers are fullscreen-focus states.** Any mobile drawer, whether layers, search, or settings, uses `setMobileDrawerState` and closes other overlays.
|
|
6. **Escape has a fixed close order.** See [controls.js::setupKeyboardControls](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js): search, settings, mobile drawer, floating menu, toolbar hub, locked object.
|
|
|
|
## Adding A Button Or Overlay
|
|
|
|
1. Add the button in the `.earth-toolbar` container in [index.html](/home/ray/dev/linkong/planet/frontend/public/earth/index.html), using the existing `floating-btn liquid-glass-surface earth-toolbar-btn` class pattern.
|
|
2. Decide whether it is a standalone action, a floating menu, or a mutually coordinated overlay.
|
|
3. For a coordinated overlay, call `closeTransientMobileOverlays({ except: "<your-key>" })` when opening it.
|
|
4. Add the reciprocal close branch inside `closeTransientMobileOverlays`, so other overlays can close yours.
|
|
5. If the new overlay should coexist with an existing overlay, exclude that peer on both sides of the matrix.
|
|
6. Add an Escape close path in `setupKeyboardControls`.
|
|
7. On mobile, use `setMobileDrawerState({ open: true, card: "<your-card>" })` for drawer-style panels.
|
|
|
|
## Current Implementation Locations
|
|
|
|
- Coordinator: [controls.js::closeTransientMobileOverlays](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js)
|
|
- Settings overlay: [controls.js::openSettingsModal / closeSettingsModal](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js)
|
|
- Search overlay: [controls.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js), imported from the search module
|
|
- News/live overlay: [tv.js::setTVPanelVisible](/home/ray/dev/linkong/planet/frontend/public/earth/js/tv.js), with the News tab in [news.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/news.js)
|
|
- Mobile layer drawer: [controls.js::setMobileDrawerState](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js)
|
|
- Floating menu: [controls.js::bindFloatingMenu](/home/ray/dev/linkong/planet/frontend/public/earth/js/controls.js)
|
|
- Toolbar DOM: [index.html](/home/ray/dev/linkong/planet/frontend/public/earth/index.html)
|