Add lazy loading for layers in GeoSet Multi Map

[lhawkman27]

Summary

• Add per-layer Lazy Loading option to the GeoSet Multi Map chart, enabling three-phase layer loading:
  • Phase 1 (Autozoom): Layers with autozoom load in parallel first — the map canvas gates on this phase to prevent viewport jumps
  • Phase 2 (Eager): Remaining non-lazy, non-autozoom layers load in parallel and appear incrementally
  • Phase 3 (Lazy): Layers marked as lazy load in small batches in the background
• Extract shared layer orchestration utilities (multiUtils.ts) from Multi.tsx for testability and reuse
• Unify the DeckSliceConfig type and normalizeDeckSlices function between the map plugin and DeckSlicesControl, eliminating duplication

Focus Score

8/10 — All changes are focused on the lazy loading feature and directly related refactoring. The shared type unification and utility extraction are necessary to support the feature cleanly. Minor scope expansion for wiki documentation updates.

Detailed Summary of Each File Changed

File	Changes
GeoSetMultiMap/Multi.tsx	Refactored loadLayers into loadSingleLayer (per-layer) + loadLayersOrchestrated (three-phase orchestrator). Added generation counter (loadGenerationRef) to cancel stale lazy chains. Layer visibility for initiallyHidden layers is pre-set from config at the start of loadLayers — before any network requests — so the legend checkbox and map never flash visible. Category visibility is set via hideCategoriesIfNeeded when layers finish loading (categories aren't known until data is fetched). layerStatesWithVisibility includes a synchronous fallback to !entry.initiallyHidden as a render-time safety net. Loading gate checks for autozoom layers to prevent viewport jump — if autozoom layers exist, waits for phase 1; otherwise shows map immediately after metadata fetch.
GeoSetMultiMap/multiUtils.ts	Exports DeckSliceConfig interface (with lazyLoading), resolveLayerAutozoom (disables autozoom when lazy), normalizeDeckSlices (handles legacy number[] format), and loadLayersOrchestrated (three-phase: autozoom parallel → eager parallel → lazy batched, with staleness abort).
geoset-map-chart/src/index.ts	Exports normalizeDeckSlices and DeckSliceConfig type from the plugin's public API.
test/GeoSetMultiMap/multiUtils.test.ts	27 tests covering resolveLayerAutozoom, normalizeDeckSlices, and loadLayersOrchestrated (autozoom-only, eager-only, lazy-only, mixed three-phase ordering, staleness abort at phase boundaries, null filtering, batch size enforcement, sync throw handling, rejection propagation).
DeckSlicesControl/index.tsx	Added Lazy Loading toggle to per-layer settings popover. Replaced duplicate normalizeValue with shared normalizeDeckSlices. Auto-disables autozoom when lazy loading is toggled on, restores prior autozoom value when toggled off. Context-dependent tooltip messaging.
tsconfig.json	Added path mapping for @superset-ui/geoset-map-chart to enable direct TS imports from DeckSlicesControl to the plugin source.
wiki/Development-Guide.md	Added multiUtils.ts entry to the Plugin Architecture file table. Added Layer Loading Orchestration section documenting the three-phase loading strategy and staleness handling.
wiki/GeoSet-Multi-Map.md	Added documentation table for per-layer settings popover options including Lazy Loading behavior. Added Layer Loading Order section explaining the three-phase user-facing behavior.

Test Plan

• Unit tests: Run npx jest multiUtils.test.ts — all 27 tests should pass covering three-phase orchestration logic, staleness, batching, null handling, and error propagation
• Autozoom-only map: Open a Multi Map where all layers have autozoom enabled — map should render after all layers load with correct viewport (no jump)
• Mixed autozoom + eager: Configure some layers with autozoom off — map renders after autozoom layers, then non-autozoom eager layers appear incrementally
• All-lazy map: Set all layers to lazy — map renders immediately after metadata fetch, layers trickle in
• No-autozoom map: Disable autozoom on all layers — map renders immediately after metadata fetch
• Three-phase ordering: With autozoom + eager + lazy layers, verify autozoom loads first, then eager, then lazy
• Staleness cancellation: While layers are loading, change a filter or form data that triggers a reload — stale chain should abort and new load starts fresh
• Auto Zoom interaction: Toggle lazy loading on — verify autozoom checkbox is disabled and unchecked. Toggle lazy loading off — verify autozoom restores to its prior value
• Static Viewport + Lazy Loading: With Static Viewport enabled, verify autozoom remains disabled regardless of lazy loading state and tooltip reflects the correct reason
• Initially Hidden + Lazy: Configure a lazy layer as hidden by default — verify it loads in the background with a spinner in the legend, and when loading completes the layer remains hidden with no visible flash. Toggle it visible from the legend checkbox
• Settings popover reopen: Open settings, change values, close without saving, reopen — verify draft state resets to saved values

🤖 Generated with Claude Code

[ethanbienstock]

Fix: Hidden + Lazy layer flash

When a layer was configured as both Hidden by Default and Lazy Loading, it would briefly flash visible on the map when loading completed. The legend checkbox would also flicker (checked → unchecked).

Root cause: The old code used a useEffect to detect newly-loaded layers and set their visibility to false. This created a two-render gap — the layer was added to state in render 1 (visible by default), then hidden in render 2 when the effect fired. That one-frame gap was the flash.

Fix (b0a65ba): Layer visibility is now pre-set from config at the start of loadLayers, before any network requests begin. Since initiallyHidden is known from the slice configuration upfront, there's no reason to wait for the layer data to arrive. Category visibility is still set on load (categories aren't known until data is fetched). As an additional safety net, layerStatesWithVisibility falls back to !entry.initiallyHidden during render if the visibility state hasn't been populated yet.

[ethanbienstock]

Works perfectly