# Widget Status System

## Overview

The Widget Status System transforms the Kollabor CLI status bar into an interactive dashboard. Navigate between widgets, trigger actions, and control application state without leaving the terminal interface.

**Key Features:**
- Interactive navigation with keyboard shortcuts
- Script-based widgets for zero-code customization
- Inline editors for real-time value adjustment
- Widget picker for easy customization
- Background color customization
- Visual feedback for selection and activation

## Quick Start

### Your First Widget in 30 Seconds

```bash
# 1. Create widget directory
mkdir -p ~/.kollabor-cli/status-widgets

# 2. Create a simple widget script
cat > ~/.kollabor-cli/status-widgets/hello.sh <<'EOF'
#!/bin/bash
# widget-id: hello
# name: Hello Widget
# description: Shows a friendly greeting
echo "Hello!"
EOF

# 3. Make it executable
chmod +x ~/.kollabor-cli/status-widgets/hello.sh

# 4. Launch Kollabor and press Tab to enter Navigation Mode
```

## Navigation Modes

### Input Mode (Default)
- Type messages in the input box
- Press `Tab` to enter Navigation Mode
- Press `F1` or `?` for help

### Navigation Mode
- **Input box is hidden** (not just blurred)
- Arrow keys move selection between widgets
- `Enter` activates selected widget
- `e` enters Edit Mode
- `Esc` returns to Input Mode
- Mode indicator shows "NAVIGATE"

### Edit Mode
- Press `e` from Navigation Mode
- Mode indicator shows "EDIT"
- **Slots visible**: Shows "+" between widgets for adding new widgets
- **Empty rows visible**: All available rows shown
- Arrow keys navigate between widgets AND slots
- `Enter` on slot opens Widget Picker
- `Enter` on widget activates it
- `d` deletes widget (with confirmation if last in row)
- `c` toggles widget background color
- `x` toggles widget effect (none -> shimmer -> pulse -> ultra)
- `A` adds new row (up to 6 max)
- `R` removes empty row
- `Esc` returns to Navigation Mode

## Keyboard Shortcuts

### Global (Any Mode)
- `Tab` - Enter Navigation Mode
- `F1` or `?` - Show help overlay

### Navigation Mode
- `Left`/`Right` - Move between widgets
- `Up`/`Down` - Move between rows
- `Enter` - Activate selected widget
- `e` - Enter Edit Mode
- `Esc` - Return to Input Mode
- `Home` - Jump to first widget
- `End` - Jump to last widget
- `1-9` - Quick jump to widget N
- `Space` - Quick toggle (toggle widgets)

### Edit Mode
- `Left`/`Right` - Move between widgets AND slots
- `Up`/`Down` - Move between rows (including empty)
- `Enter` on widget - Activate widget
- `Enter` on slot - Open Widget Picker
- `d` - Delete selected widget
- `c` - Toggle widget background color
- `Esc` - Return to Navigation Mode

## Widget Types

### Command Widgets
Execute slash commands when activated:
- `profile` - Opens profile selector
- `agent` - Opens agent switcher
- `model` - Opens model selector
- `tmux` - Opens tmux session manager

### Toggle Widgets
Click to cycle through states:
- `test-toggle` - Cycles: TEST:OFF, TEST:ON, TEST:AUTO

### Inline Edit Widgets
Edit values directly in status area:
- `temperature` - Adjust LLM temperature (0.0-2.0)
- `max-tokens` - Set max response tokens (100-8000)
- `profile-switcher` - Quick profile selection

### Script Widgets
Custom widgets from shell scripts:
- Place in `~/.kollabor-cli/status-widgets/` (global)
- Place in `.kollabor-cli/status-widgets/` (project-specific)

## Creating Custom Widgets

### Basic Widget Template

```bash
#!/bin/bash
# widget-id: my-widget
# name: My Widget
# description: Shows useful information
# category: custom
# interactive: false
# min-width: 10

# Your widget code here
echo "42"
```

### Interactive Widget (Modal)

**Main widget** (`git-branch.sh`):
```bash
#!/bin/bash
# widget-id: git-branch
# name: Git Branch
# description: Current git branch
# category: git
# interactive: true
# interaction-type: modal
# on-activate: ./git-branch-modal.sh
# refresh: 5s
# min-width: 15

branch=$(git branch --show-current 2>/dev/null || echo "no-git")
dirty=$(git diff --quiet 2>/dev/null || echo "*")
echo "⎇ ${branch}${dirty}"
```

**Modal handler** (`git-branch-modal.sh`):
```bash
#!/bin/bash
# Returns JSON defining modal options

cat <<EOF
{
  "title": "Git Branch Actions",
  "options": [
    {
      "label": "View Status",
      "command": ["git", "status"],
      "display": "terminal"
    },
    {
      "label": "Pull Latest",
      "command": ["git", "pull"],
      "confirm": true
    }
  ]
}
EOF
```

### Refresh Strategies

```bash
# Manual (default)
# refresh: manual

# Time-based polling
# refresh: 5s      # Every 5 seconds
# refresh: 1m      # Every 1 minute

# Event-based
# refresh: on-event
# hooks: post_user_input, pre_api_request

# Run once at startup
# refresh: once

# Smart (time + events)
# refresh: 10s
# hooks: post_user_input
```

## Widget Metadata Fields

| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `widget-id` | string | Yes | - | Unique identifier (kebab-case) |
| `name` | string | Yes | - | Display name in picker |
| `description` | string | Yes | - | Brief description |
| `category` | string | No | "custom" | Widget category |
| `interactive` | boolean | No | false | Widget is clickable |
| `interaction-type` | string | No | - | modal, toggle, action, inline_edit |
| `on-activate` | string | No | - | Script to run on activation |
| `refresh` | string | No | "manual" | Refresh strategy |
| `hooks` | string | No | - | Comma-separated hook names |
| `min-width` | int | No | 10 | Minimum width in characters |
| `timeout` | string | No | "5s" | Max execution time |
| `color` | boolean | No | true | Allow ANSI color codes |

## Customization

### Visual Effects

Widgets can have animated visual effects applied:
- `none` - No effect (default)
- `shimmer` - Subtle wave animation
- `pulse` - Pulsing brightness animation
- `ultra` - Fast shimmer animation

Press `x` in Edit Mode to cycle through effects.

### Widget Background Colors

Press `c` in Edit Mode to cycle widget background colors:
- `none` - Default (transparent)
- `dark0` - Dark background
- `dark1` - Slightly lighter
- `primary0` - Primary accent
- `secondary0` - Secondary accent

### Adding Widgets

1. Press `Tab` to enter Navigation Mode
2. Press `e` to enter Edit Mode
3. Navigate to a "+" slot
4. Press `Enter` to open Widget Picker
5. Select a widget to add

### Deleting Widgets

1. Press `Tab` to enter Navigation Mode
2. Press `e` to enter Edit Mode
3. Navigate to the widget
4. Press `d` to delete
5. Confirm if prompted

## Configuration

Widget layout is stored in `~/.kollabor-cli/config.json`:

```json
{
  "status_layout": {
    "version": 1,
    "rows": [
      {
        "id": 1,
        "visible": true,
        "widgets": [
          {
            "id": "cwd",
            "width": {"type": "auto"},
            "color": "none",
            "effect": "none"
          }
        ]
      }
    ]
  }
}
```

## Examples

### Git Status Widget

```bash
#!/bin/bash
# widget-id: git-status
# name: Git Status
# description: Shows git repository status
# category: git
# interactive: true
# interaction-type: modal
# on-activate: ./git-status-modal.sh
# refresh: on-event
# hooks: post_user_input
# min-width: 20

if ! git rev-parse --git-dir > /dev/null 2>&1; then
    echo "no git"
    exit 0
fi

branch=$(git branch --show-current 2>/dev/null)
dirty=$(git diff --quiet 2>/dev/null || echo "*")
echo "⎇ ${branch}${dirty}"
```

### Docker Status Widget

```bash
#!/bin/bash
# widget-id: docker-status
# name: Docker Status
# description: Shows running container count
# category: docker
# interactive: true
# interaction-type: action
# on-activate: ./docker-actions.sh
# refresh: 10s
# min-width: 10

if ! command -v docker &> /dev/null; then
    echo "no docker"
    exit 0
fi

running=$(docker ps -q 2>/dev/null | wc -l | tr -d ' ')
total=$(docker ps -aq 2>/dev/null | wc -l | tr -d ' ')
echo "🐳 ${running}/${total}"
```

### Python Environment Widget

```bash
#!/bin/bash
# widget-id: python-env
# name: Python Environment
# description: Shows active Python environment
# category: python
# interactive: false
# refresh: once
# min-width: 15

if [ -n "$VIRTUAL_ENV" ]; then
    env_name=$(basename "$VIRTUAL_ENV")
    python_ver=$(python --version 2>&1 | cut -d' ' -f2)
    echo "🐍 ${env_name} (${python_ver})"
elif [ -n "$CONDA_DEFAULT_ENV" ]; then
    python_ver=$(python --version 2>&1 | cut -d' ' -f2)
    echo "🐍 ${CONDA_DEFAULT_ENV} (${python_ver})"
else
    echo "🐍 system"
fi
```

## Security

- Scripts run with your user permissions
- Timeout protection (default 5s per widget)
- Input validation prevents command injection
- Only scripts from designated directories are executed

## Troubleshooting

### Widget Not Appearing
1. Check script is executable: `chmod +x widget.sh`
2. Verify required metadata fields are present
3. Check script syntax: `bash -n widget.sh`
4. View logs: `~/.kollabor-cli/projects/<encoded-path>/logs/kollabor.log`

### Widget Timing Out
- Increase timeout in metadata: `# timeout: 10s`
- Optimize script performance
- Consider caching output

### Interactive Widgets Not Responding
- Verify `on-activate` script path is correct
- Check modal handler returns valid JSON
- Test modal handler manually: `./modal-handler.sh`

## See Also

- [Interactive Status Widgets Specification](../specs/interactive-status-widgets-spec.md)
- [Widget Status System Architecture](../reference/widget-status-system.md)
- [Design System](../reference/design-system.md)
