planet/docs/technical/en/earth-toolbar-overlay-coordination.md

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
• Frontend Layout Guidelines

Toolbar Button Directory

The toolbar is marked by .earth-toolbar-btn in 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 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:

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: 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, 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
• Settings overlay: controls.js::openSettingsModal / closeSettingsModal
• Search overlay: controls.js, imported from the search module
• News/live overlay: tv.js::setTVPanelVisible, with the News tab in news.js
• Mobile layer drawer: controls.js::setMobileDrawerState
• Floating menu: controls.js::bindFloatingMenu
• Toolbar DOM: index.html