boc/docs/design/foundations/COMPONENT_DECISION_TREE.md

# COMPONENT DECISION TREE

**Which Component Should I Use?**

| | |
|---|---|
| **Version** | 1.0 |
| **Status** | LOCKED |
| **Scope** | All Landvex & quiXzoom products |

---

## How to Use This Document

Start at the top. Answer each question. Follow the path to the recommended component.

If no existing component fits, apply the **New Component Rule** (see Design Specification §8.2):
1. Can an existing component be used?
2. Can a variant be created?
3. Can a modifier be used?
4. Can a new state solve the problem?

Only then define a new component.

---

## User Actions

```
Need user action?
├── Yes → Primary action?
│   ├── Yes → Button (Primary)
│   └── No → Multiple options?
│       ├── Yes → Select / Dropdown
│       └── No → Toggle state?
│           ├── Yes → Switch / Checkbox
│           └── No → Navigation?
│               ├── Yes → Navigation / Sidebar
│               └── No → Search?
│                   ├── Yes → Search
│                   └── No → Command Palette
└── No → Need information display?
    └── Yes → See Information Display
```

## Information Display

```
Need to display information?
├── Yes → Tabular data?
│   ├── Yes → Simple table?
│   │   ├── Yes → Table
│   │   └── No → Sorting, filtering, pagination?
│   │       ├── Yes → Data Grid
│   │       └── No → Table
│   └── No → Spatial data?
│       ├── Yes → Map Panel
│       └── No → Summary metric?
│           ├── Yes → KPI Card
│           └── No → Grouped content?
│               ├── Yes → Card / Accordion
│               └── No → Single item?
│                   ├── Yes → Badge / Alert
│                   └── No → Tooltip
└── No → Need user input?
    └── Yes → See User Input
```

## User Input

```
Need user input?
├── Yes → Text input?
│   ├── Yes → Single line?
│   │   ├── Yes → Input
│   │   └── No → Textarea
│   └── No → Choice from options?
│       ├── Yes → Single choice?
│       │   ├── Yes → Radio / Select
│       │   └── No → Multiple choice?
│       │       ├── Yes → Checkbox / Multi-select
│       │       └── No → Toggle?
│       │           ├── Yes → Switch
│       │           └── No → Date / time?
│       │               ├── Yes → Date Picker
│       │               └── No → Coordinate?
│       │                   ├── Yes → Coordinate Picker
│       │                   └── No → File?
│       │                       ├── Yes → File Upload
│       │                       └── No → Input (custom)
│       └── No → Search / filter?
│           ├── Yes → Search
│           └── No → Command Palette
└── No → Need feedback?
    └── Yes → See Feedback
```

## Feedback

```
Need to provide feedback?
├── Yes → Blocking action?
│   ├── Yes → Modal / Dialog
│   └── No → Transient notification?
│       ├── Yes → Toast
│       └── No → Contextual message?
│           ├── Yes → Alert (inline) / Tooltip
│           └── No → Status indicator?
│               ├── Yes → Badge
│               └── No → Progress?
│                   ├── Yes → Progress / Skeleton
│                   └── No → Empty State
└── No → Navigation or structure?
    └── Yes → See Navigation
```

## Navigation

```
Need navigation?
├── Yes → Primary navigation?
│   ├── Yes → Top-level sections?
│   │   ├── Yes → Navigation
│   │   └── No → Sidebar
│   └── No → Secondary navigation?
│       ├── Yes → Tabs / Breadcrumb
│       └── No → Contextual navigation?
│           ├── Yes → Pagination / Menu
│           └── No → Command Palette
└── No → Consider: is this a new component?
    └── Apply New Component Rule
```

## Landvex-Specific (Domain Components)

```
Need Landvex-specific component?
├── Yes → Geospatial data?
│   ├── Yes → Map visualization?
│   │   ├── Yes → Map Panel
│   │   └── No → Layer control?
│   │       ├── Yes → Layer Selector
│   │       └── No → Feature inspection?
│   │           ├── Yes → Geospatial Inspector
│   │           └── No → Coordinate input?
│   │               └── Yes → Coordinate Picker
│   └── No → Mission data?
│       ├── Yes → Mission status?
│       │   ├── Yes → Mission Status
│       │   └── No → Mission timeline?
│       │       └── Yes → Timeline Panel
│       └── No → Asset data?
│           ├── Yes → Asset summary?
│           │   ├── Yes → Asset Summary
│           │   └── No → Dataset preview?
│           │       └── Yes → Dataset Card
│           └── No → KPI display?
│               └── Yes → KPI Card
└── No → See general decision trees above
```

---

## Quick Reference Table

| Need | Component | Tier |
|------|-----------|------|
| Primary action | Button | 1 |
| Text input | Input | 1 |
| Choice from list | Select | 1 |
| Content container | Card | 1 |
| Overlay dialog | Modal | 1 |
| Navigation | Navigation / Sidebar | 1 |
| Tabular data | Table / Data Grid | 1 |
| Search | Search | 1 |
| Map display | Map Panel | 1 |
| Status indicator | Badge | 2 |
| Message | Alert / Toast | 2 |
| Help text | Tooltip | 2 |
| Collapsible content | Accordion | 2 |
| Content switching | Tabs | 2 |
| Location indicator | Breadcrumb | 2 |
| Page navigation | Pagination | 2 |
| No content | Empty State | 2 |
| Loading | Skeleton | 2 |
| Key metric | KPI Card | 3 |
| Map tools | Map Overlay Panel | 3 |
| Layer control | Layer Selector | 3 |
| Mission state | Mission Status | 3 |
| Data preview | Dataset Card | 3 |
| Feature details | Geospatial Inspector | 3 |
| Asset overview | Asset Summary | 3 |
| Coordinate input | Coordinate Picker | 3 |
| Time data | Timeline Panel | 3 |

---

## Relationship to Other Documents

| Document | Role |
|----------|------|
| `LANDVEX_DESIGN_SPECIFICATION.md` §8 | Component tiers and inheritance |
| `COMPONENT_TEMPLATE.md` | How to document a component |
| `DESIGN_ANTI_PATTERNS.md` | What not to do |
| `COMPONENT_DECISION_TREE.md` | Which component to use |

---

## ÄNDRINGSHISTORIA

| Version | Datum | Beskrivning |
|---------|-------|-------------|
| 1.0 | 2026-07-02 | Initial decision trees for actions, information, input, feedback, navigation, and Landvex-specific |

---

## STATUS

**LOCKED**

- Mindre revideringar: 1.x-serien
- Brytande ändringar: Kräver Architecture Review, ny major-version (2.0+)