"/home/yossef/notes/git/projects/maplibra/flows/Theme Change.md"

path: maplibra/flows/Theme Change.md

- **fileName**: Theme Change
- **Created on**: 2026-06-16 00:48:42

Theme Change

Purpose: How the app switches between light and dark themes without recreating map layers.

Related: ../Home.md, ../Architecture.md, ../modules/Layer Management.md, ../modules/UI Components.md, ../modules/Path Renderer.md

Theme Architecture

Themes are defined in theme.js with:

• mapStyle — Mapbox style URL or JSON object
• colors — Color map for all layer types (walls, floors, labels, background, etc.)

Theme Change Flow

1. User toggles theme (or Android dispatches theme-changed)
2. ThemeController.handleThemeToggle() → script.js handleThemeChange()
3. map.setStyle(themeConfig.mapStyle, { diff: false })
4. Wait for style.load event
5. applyThemeToMap() — update background, building shell, labels
6. LayerManager.reapplyThemeColors() — update all style layers
   • Background color
   • Building shell extrusion color
   • Label text and halo colors
   • Dynamic style layers (fill-extrusion with selected/hover states)
7. LayerManager.addBuildingShell(floors) — rebuild building shell
8. floorDataManager.loadAndRenderFloor(currentFloorId) — re-render current floor
9. PathRenderer.setTheme() — update route line colors
10. PathfindingController.renderer.updateFilters() — update route filters

Key Design

• In-place color updates — theme swaps do not recreate sources or layers
• LayerManager.styleLayerIds tracks which layers need color updates
• fill-extrusion-color uses case expressions with feature-state for selected/hover
• Mapbox style is fully replaced (diff: false) because the basemap may be completely different

Important Files

• theme.js — Theme definitions and color maps
• src/ui/ThemeController.js — Toggle button and event handling
• src/layer-manager.js — setTheme(), reapplyThemeColors()
• script.js — handleThemeChange() orchestration

How It Connects

• ThemeController is created lazily in script.js after map init

• Theme change triggers a full style reload but preserves app state

• LayerManager re-applies colors to all existing layers

• FloorDataManager re-renders the current floor with new colors

• PathRenderer updates route line colors

• Android WebView gets updated basemap style via window.__INGUIDE_BASEMAP_STYLE__

  continue:[[]]
  before:[[]]