pandora-kit 0.3.0

Interactive TUI toolkit for the Hefesto framework
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

# pandora menu — Interactive Tree Menu

Displays a hierarchical menu from JSON input and lets the user navigate, expand/collapse branches, and select a leaf node.

## Usage

```
pandora menu [OPTIONS] [FILE]
```

## Arguments

| Argument | Description                             |
|----------|-----------------------------------------|
| `FILE`   | Path to input file (reads stdin if empty)|

## Options

| Flag               | Default              | Description                        |
|--------------------|----------------------|------------------------------------|
| `-f`, `--format`   | `auto`               | Input format: auto, json, plano    |
| `-t`, `--title`    | `"Menú"`             | Title in the popup header          |
| `-W`, `--width`    | `0` (auto)           | Popup width                        |
| `-H`, `--height`   | `0` (auto)           | Popup height                       |
| `--guide`          |                      | Show this guide                    |

## Format detection

When `--format auto` (default), the format is detected from the file extension:

| Extension | Format |
|-----------|--------|
| `.json`   | json   |
| other     | plano  |

For stdin (no FILE argument), defaults to `plano`.

## Input formats

### JSON

```json
[
  {
    "id": 1,
    "text": "Option 1",
    "children": [
      { "id": 2, "text": "Sub-option 1" }
    ]
  }
]
```

| Field      | Type     | Description                              |
|------------|----------|------------------------------------------|
| `id`       | number   | Unique id (required, must be unique)     |
| `text`     | string   | Display text                             |
| `children` | array    | Optional nested nodes                    |

### Plano

One path per line, segments separated by `/`:

```
Archivo/Nuevo/Documento
Archivo/Abrir
Editar/Deshacer
```

Ids are auto-generated. No comments.

## Output

On selection, prints the full path from root to leaf, segments joined by `/`:

```
Editar/Deshacer/Deshacer escritura
```

## Exit codes

| Code | Meaning                          |
|------|----------------------------------|
| 0    | Selection made (text on stdout)  |
| 1    | User cancelled (no output)       |

## Examples

```bash
# JSON file (auto-detected)
pandora menu menu.json

# Plano file (auto-detected from .txt)
pandora menu menu.txt

# Explicit format
pandora menu -f plano menu.txt

# Pipe stdin (defaults to plano)
printf 'Archivo/Nuevo\nArchivo/Abrir\n' | pandora menu

# Custom title
pandora menu menu.json -t "Projects"

# Explicit size
pandora menu menu.json -W 60 -H 20
```

## Mouse

- **Click item**: select that item
- **Drag**: click and hold the border or title bar to move the popup

## Keyboard

| Key              | Action                          |
|------------------|---------------------------------|
| `↑` / `k`        | Navigate up                     |
| `↓` / `j`        | Navigate down                   |
| `Tab`            | Navigate down                   |
| `Shift+Tab`      | Navigate up                     |
| `Enter`          | Expand/collapse branch, or select leaf |
| `→` / `Space`    | Expand branch                   |
| `←`              | Collapse branch                 |
| `gg`             | Go to first item                |
| `G`              | Go to last item                 |
| `Esc` / `q`      | Cancel                          |
| `Ctrl` + `c`     | Emergency exit                  |