# Popup System - LLM Guide

## Quick Start

Build tmux popups by composing Command objects:
```python
from tmux_popup import Popup
from tmux_popup.gum import GumStyle, GumInput

popup = Popup(width="65", title="Session")
result = popup.add(
    GumStyle("Header", header=True),
    GumInput(value="default")
).show()
```

## Key Concepts

**Commands render, Popups execute.** Each gum command knows how to render itself to shell script. The Popup runner executes the combined script in tmux display-popup.

**Value/display separation.** Use tuples for choices when display differs from value:
```python
GumChoose([("id", "Display Name")])  # Returns "id"
```

**Empty strings become spacers.** `popup.add("", "text", "")` adds blank lines.

## Best Practices

### Be Explicit with Instructions
Instead of: "Show a popup"
Use: "Create a popup with GumStyle header, info message, and GumInput for command editing"

### Compose, Don't Chain
```python
# Good - explicit composition
popup.add(
    GumStyle("Title", header=True),
    GumInput(placeholder="Enter..."),
)

# Avoid - no method chaining
popup.header("Title").input("Enter...")  # Doesn't exist
```

### Handle Results Properly
Commands that return values (Input, Choose, Confirm) return None on cancel:
```python
result = popup.add(GumInput()).show()
if result:  # User entered something
    process(result)
```

### Use Style Shortcuts
GumStyle has built-in shortcuts for common patterns:
- `header=True` - Bold, centered, bordered
- `info=True` - Blue text
- `warning=True` - Yellow bold
- `error=True` - Red bold

### Parallel Command Selection
For multiple independent selections, use separate popups or GumFilter with limit=0:
```python
# Multiple selection in one popup
selected = popup.add(
    GumFilter(options, limit=0, fuzzy=True)
).show()  # Returns list
```

## Common Patterns

### SSH Command Confirmation
```python
popup.add(
    GumStyle("Remote Execution", header=True),
    GumStyle(f"Command: {cmd}", info=True),
    "",
    "Edit or press Enter to execute",
    GumInput(value=cmd, placeholder="ESC to cancel")
).show()
```

### Process Selection
```python
rows = [["PID", "Name", "Status"], ...]
popup.add(
    GumTable(rows[1:], headers=rows[0], return_column=2)
).show()  # Returns selected row's Name column
```

### Multi-Step Workflow
```python
# Step 1: Choose action
action = popup.add(GumChoose([...]).show()

# Step 2: Get details based on action
if action == "edit":
    text = Popup().add(GumWrite()).show()
```

## Implementation Notes

- Commands are single-use (create new for each popup)
- Temp files auto-cleanup after show()
- Raw shell commands can be mixed with Command objects
- All gum styling flags available via command constructors