pandora-kit 0.4.6

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

# Pandora — CLI Toolkit with TUI Popups

Pandora provides interactive TUI popups for use in scripts and terminal workflows.

## Usage

```
pan [OPTIONS] <COMMAND>
```

## Options

| Flag        | Description                     |
|-------------|---------------------------------|
| `--guide`   | Show this guide                 |

## Subcommands

| Command       | Description                                        |
|---------------|----------------------------------------------------|
| `confirm`     | Confirmation popup (y/n). Returns 0 or 1.          |
| `choose`      | Interactive item selector.                         |
| `filter`      | Filter & select popup with text input.             |
| `spin`        | Animated spinner with optional command execution.  |
| `log`         | Print a formatted, colored log line.               |
| `input`       | Capture text input from the user.                  |
| `file`        | Interactive file browser for selecting files.      |
| `menu`        | Interactive tree menu from JSON stdin.             |

Run `pan <subcommand> --guide` for detailed documentation of each command.

## Capturing output

All interactive subcommands write the result to **stdout** and use the same
exit code convention:

| Exit code | Meaning                          |
|-----------|----------------------------------|
| 0         | Selection made (result on stdout)|
| 1         | Cancelled (no output, or empty)  |

The TUI rendering goes directly to `/dev/tty`, not to stdout, so you can
capture the result safely using any of the patterns below.

> ⚠️ Requires `pan >= 0.4.5`. Earlier versions may fail inside `$(...)`
> because crossterm writes the cursor position query (`\x1b[6n`) to
> stdout instead of the terminal. The binary now redirects stdout to
> `/dev/tty` during initialization and restores it before output.

### Pattern 1 — Redirección a archivo (recomendado)

No crea subshells. Funciona en cualquier shell (bash, zsh, sh).

```bash
pan menu menu.txt > /tmp/result.txt
read -r SEL < /tmp/result.txt
```

En un bucle hasta salir o cancelar:

```bash
#!/bin/bash

ENTRY_FILE=$(mktemp /tmp/pan.XXXXXX)
trap 'rm -f "$ENTRY_FILE"' EXIT

while true; do
  pan menu menu.txt > "$ENTRY_FILE" || break
  read -r SEL < "$ENTRY_FILE"
  [ -z "$SEL" ] && break
  echo "Seleccionaste: $SEL"
done
```

### Pattern 2 — Command substitution `$(...)`

Simple, directo, funciona con `pan >= 0.4.3`.

```bash
SEL=$(pan menu menu.txt) || exit 1
```

En un bucle:

```bash
#!/bin/bash

while true; do
  SEL=$(pan menu menu.txt) || break
  [ -z "$SEL" ] && break
  echo "Seleccionaste: $SEL"
done
```

### Pattern 3 — Variable por defecto con cancelación

```bash
SEL=$(pan menu menu.txt)
case "$SEL" in
  "") echo "Cancelado" ; exit 1 ;;
  "Salir") exit 0 ;;
  *) echo "Elegiste $SEL" ;;
esac
```

### Pattern 4 — Confirm (solo exit code, no hay output que capturar)

```bash
pan confirm -m "¿Continuar?" && echo "Aceptado" || echo "Cancelado"

if pan confirm -t "Actualizar" -m "¿Proceder?"; then
  make deploy
fi
```

### Notas importantes

| No hagas esto                         | Razón                                          |
|---------------------------------------|-------------------------------------------------|
| `ENTRY=$(<archivo)`                   | Crea un subshell innecesario                    |
| `pan menu ... \| while read SEL`      | El pipe crea un subshell, mismo problema        |
| `read SEL <<< "$(pan menu ...)"`      | `$(...)` dentro de un here-string, igual        |
| `pan menu ... < /dev/tty`             | Ya no es necesario, el binario lo hace solo     |