Skip to content

docs: ADR for layout handler and styling of MMGIS. #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sandesh-sp wants to merge 1 commit into
base: development
Choose a base branch
from
Open

docs: ADR for layout handler and styling of MMGIS. #23

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
334 changes: 334 additions & 0 deletions docs/adr/02102026-layout-and-styling-architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,334 @@
# Layout and Styling Architecture for MMGIS

- **Status**: PROPOSED
- **Date**: 2026-02-10
- **Deciders**: MMGIS Core Team
- **Tags**: layout, styling, ui, panel-system, multi-panel, theming

---

## Executive Summary

Modernize MMGIS's layout and styling architecture to support a flexible, themable plugin framework that aligns with USWDS/Horizon design systems.

**Key Changes**:
- **Layout**: Enhance current panel system with multi-panel support, minimize/close controls, and modern spacing
- **Styling**: Migrate from hard-coded dark theme to flexible, design system-aligned theming
- **Configuration**: Extend mission/tool configs to support panel configuration and theme customization

**Benefits**:
- **Multi-Panel Support**: Multiple plugins can be open simultaneously with independent controls
- **Usability**: Covers our core use cases with incremental enhancement path
- **Consistency**: Align with existing design standards (USWDS/Horizon)
- **Future-proof**: Foundation for grid-based layout system in later development cycle

---

## Terminology Note

To avoid confusion, we use internal terms that differ from MMGIS framework conventions:

| Our Term | MMGIS Framework Term | Description |
|----------|---------------------|-------------|
| Tool | Mission | Each unique instance of MMGIS dashboard |
| Plugin / Component | Tool | Individual interactive components (Draw, Measure, etc.) |

*Note: Custom plugins/components we develop will be located in the `src/essence/Tools/` directory in MMGIS codebase.*

---

## Context and Problem Statement

### Current State: Layout

MMGIS uses a **fixed panel system** where plugins attach to pre-defined containers. Panels interact with the map in two ways:

```
┌──────────────────────────────────────────────────────────┐
│ Top Panel (Header) │
│ [Logo] [Title] [View Switcher] │
├──────────┬───────────────────────────────────────────────┤
│ │ │
│ Left │ │
│ Panel │ Map Canvas (Leaflet/Cesium) │
│ (slides) │ │
│ │ ┌─────────────┐ │
│ │ │ Floating │ │
│ │ │ Panel │ │
├──────────┴──┴─────────────┴──────────────────────────────┤
│ Bottom Panel (slides up) │
└──────────────────────────────────────────────────────────┘
```

#### Panel Types

| Type | Behavior | Code Configuration | Examples |
|------|----------|-------------------|----------|
| **Left Panel** | Slides from left, resizes map canvas | `height: 0` | Info Tool |
| **Bottom Panel** | Slides from bottom, resizes map canvas | `height > 0` | Measure Tool |
| **Floating Panel** | Overlays map, doesn't resize canvas | `"separatedTool": true` | Legend Tool |

**Configuration Example**:
```javascript
// Left Panel Tool
const InfoTool = {
height: 0, // Triggers left panel
width: 300,
make: function() { ... }
}

// Floating Panel Tool (in config)
{
"name": "LegendTool",
"separatedTool": true // Becomes floating
}
```

#### Desktop vs Mobile View

| Feature | Desktop | Mobile |
|---------|---------|--------|
| Panel Support | All three types | Bottom Panel only |
| Map Views | 2D Map, 3D Globe, Image Viewer | 2D Map only |
| Toolset | All 16+ plugins | Reduced set (many hidden) |

### Problems with Current Layout

| Problem | Impact |
|---------|--------|
| **Single-Active Component** | Only one plugin active at a time; activating new one destroys previous |
| **No Panel Controls** | Cannot minimize or close panels without switching tools |
| **Limited Floating Panels** | Floating panels stack and obstruct each other |
| **Basic Visual Design** | Panels lack modern styling, spacing, and visual hierarchy |
| **No Multi-Panel Management** | Cannot manage multiple open panels simultaneously |

### Current State: Styling

MMGIS uses a **centralized CSS architecture** with a dark geospatial theme.

```
src/css/
├── mmgis.css # Core styles, :root variables, animations
├── mmgisUI.css # UI components (buttons, sliders, checkboxes)
├── external/ # Third-party library overrides
│ ├── leaflet.css
│ └── tempus-dominus.css
└── tools.css # Built-in tool-specific styles

src/essence/Tools/<ToolName>/
└── <ToolName>Tool.css # Component-specific styles
```

**Current Theming via CSS Variables**:
```css
/* mmgis.css */
:root {
--color-a: #1c1c1c; /* Dark background */
--color-b: #2e2e2e; /* Panel background */
--color-k: #000000; /* Pure black */
--main-color: #00d8ff; /* Accent color */
}
```

### Problems with Current Styling

| Problem | Impact |
|---------|--------|
| **Hard-coded Dark Theme** | No light mode or alternative themes |
| **Dynamic Inline Styles** | JavaScript frequently injects styles; hard to override |
| **High-Specificity Overrides** | Third-party library overrides require `!important` chains |
| **No Design System Integration** | Doesn't align with USWDS/Horizon standards |

---

## Decision Drivers

1. **Multi-Panel Support**: Enable multiple active plugins simultaneously (e.g., Draw + Measure + Layers)
2. **Modern Visual Design**: Improve panel styling with proper spacing, and visual hierarchy
3. **Floating Panel Management**: Better z-index and stacking management for overlapping panels
4. **Design System Alignment**: Match USWDS or Horizon for enterprise consistency
5. **Configuration-Driven**: Panel behavior and theming defined in mission/tool configs, not hard-coded
6. **Gradual Migration**: Can adopt incrementally without rewriting all 16+ existing tools
7. **Incremental Enhancement**: Build foundation for future grid-based layout system

---

## Assumptions

1. **Panel Architecture Preservation**: Current panel system (left, bottom, floating) can be enhanced without fundamental rewrite
2. **Desktop-First**: Initial implementation focuses on desktop; mobile layout improvements are future work
3. **Backward Compatibility**: Existing tools continue working with current configuration until migrated
4. **Plugin Lifecycle Compatibility**: `make()` and `destroy()` functions can be minimally updated to support multi-panel scenarios
5. **Grid Layout Deferred**: Full grid-based layout system (Gridstack.js) will be implemented in a later development cycle

---

## Considered Options

#### Option 1: Enhanced Panel System (Selected)

**Description**: Extend current panel system with multi-panel support, modern controls, and improved visual design.


**Panel Features**:
- **Multi-Panel Support**: Multiple tools can be open simultaneously
- **Panel Controls**: Minimize, maximize, close buttons on panel header
- **Modern Styling**: Box shadows, border radius, proper spacing, visual hierarchy
- **State Persistence**: Remember panel states across sessions

**Pros**:
- Minimal refactoring of existing architecture
- Works with current jQuery/D3 codebase
- Preserves existing panel types (left, bottom, floating)
- Can be implemented incrementally

**Cons**:
- Still limited to pre-defined panel positions
- Cannot arbitrarily position panels on screen
- Less flexible than full grid system

**Why chosen**:
- Delivers immediate value without major refactoring
- Addresses core usability issues (single-panel limitation)
- Provides foundation for future grid-based system
- Low risk, high impact enhancement

---

#### Option 2: Gridstack.js Grid System (Deferred to Future)

**Description**: Full grid-based layout with drag-and-drop positioning.

**Why deferred**:
- More complex than needed for current requirements
- Can be added later as enhancement to panel system
- Requires more extensive testing and migration effort
- See [Phase 6: Grid-Based Layout System](#phase-6-grid-based-layout-system-q3-2026) for planned implementation

---

#### Option 3: Complete UI Rewrite with React

**Description**: Modernize entire frontend with React framework.

**Why rejected**:
- Too disruptive for current development cycle
- Would require rewriting all 16+ existing tools
- Significant effort (months) with high risk
- Can be reconsidered in future major version

---

### Styling

#### Option 1: USWDS / Horizon

**Description**: A government-standard design system with built-in accessibility and a mature component ecosystem.

**Pros**:
- WCAG 2.1 AA compliant out of the box
- Comprehensive component library (50+ components)
- Built-in light and dark theme support
- Strong documentation and active community

**Cons**:
- May not be a perfect visual fit for all projects

---

#### Option 2: Custom Theme System (CSS Variables)

**Description**: A flexible, custom theming approach built on top of CSS variables.

**Pros**:
- Highly customizable to meet individual project needs
- Enables future creation of custom themes for different deployments

**Cons**:
- Significant upfront effort to design and maintain a theme architecture
- Requires defining and maintaining themes for each project

---

#### Decision

Adopt **USWDS / Horizon** as the default design system to ensure accessibility, consistency, and faster delivery.
In parallel, structure the codebase to support theming so that USWDS becomes one of several themes in a future theme gallery, enabling customization as needs evolve.

---

## Migration Path

### Phase 1: Panel Manager Foundation (Week 1-2)
- [ ] Create `PanelManager_.js` module for multi-panel state management
- [ ] Implement panel registration and tracking system
- [ ] Add panel state management (open, minimized, closed)
- [ ] Add theme loader (`Theme_.js`)

### Phase 2: Panel Controls & UI (Week 3-4)
- [ ] Design and implement panel header component with controls
- [ ] Add minimize, maximize, close button functionality
- [ ] Implement panel state transitions with animations
- [ ] Add keyboard shortcuts for panel controls (accessibility)
- [ ] Create modern panel styling with USWDS design tokens

### Phase 3: Multi-Panel Support (Week 5-6)
- [ ] Update `ToolController_.js` to support multiple active tools
- [ ] Refactor `make()` / `destroy()` lifecycle for multi-panel scenarios
- [ ] Implement backward compatibility layer for single-panel tools
- [ ] Add panel state persistence to database/local storage
- [ ] Test multi-panel scenarios (2-3 panels open simultaneously)

### Phase 4: Theming Integration (Week 7-8)
- [ ] Integrate USWDS CSS framework
- [ ] Create `geospatial-dark.css` preserving current theme as default
- [ ] Update panel components to use USWDS design tokens
- [ ] Replace `mmgisUI.css` components with USWDS equivalents
- [ ] Add theme switcher to Configure page

### Phase 5: Tool Migration & Testing (Week 9-10)
- [ ] Update 3-5 high-priority tools (Draw, Measure, Layers, Info, Legend)
- [ ] Test multi-panel scenarios with updated tools
- [ ] Document plugin migration guide for panel controls
- [ ] Update plugin template with panel best practices
- [ ] Conduct accessibility testing (keyboard navigation, screen readers)

---

## Future Roadmap

### Phase 6: Grid-Based Layout System
- [ ] Evaluate and integrate Gridstack.js library
- [ ] Create grid initialization in `UserInterfaceDefault_.js`
- [ ] Extend config schema with grid `layout` key
- [ ] Implement drag-and-drop panel positioning
- [ ] Add panel resizing with collision detection
- [ ] Migrate panel system to grid-based containers
- [ ] Implement responsive breakpoints for different screen sizes
- [ ] Test backward compatibility with enhanced panel system

### Phase 7: Visual Layout Builder
- [ ] Add drag-and-drop layout editor to Configure page
- [ ] Real-time preview of layout changes
- [ ] Export/import layout templates
- [ ] Component palette for quick plugin addition
- [ ] Visual grid overlay for alignment
- [ ] Layout validation and conflict detection

### Phase 8: Mobile Optimization
- [ ] Refactor `UserInterfaceMobile_.js` with responsive panel system
- [ ] Implement swipeable panel navigation
- [ ] Optimize plugin UI for touch interactions
- [ ] Add mobile-specific panel presets
- [ ] Test multi-panel scenarios on mobile devices

### Phase 9: Advanced Theming
- [ ] Dynamic theme generation from mission config
- [ ] High-contrast accessibility mode
- [ ] Theme gallery for user-contributed themes
- [ ] Theme preview in Configure page

### Phase 10: Plugin Marketplace Integration
- [ ] Sandboxed iframe layout for marketplace plugins
- [ ] Theme API for third-party plugins
- [ ] Layout validation and security checks