@valyrianjs/terminal 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/README.md +22 -22
  2. package/docs/api-reference.md +103 -103
  3. package/docs/cookbook.md +23 -23
  4. package/docs/core-concepts.md +50 -50
  5. package/docs/getting-started.md +22 -22
  6. package/docs/interaction-model.md +55 -55
  7. package/docs/local-demo.md +10 -10
  8. package/docs/session-runtime.md +97 -97
  9. package/package.json +1 -1
package/docs/core-concepts.md CHANGED
@@ -1,93 +1,93 @@
1
1
  # Core Concepts
2
2
 
3
- Esta guia explica el modelo mental del paquete antes de entrar al detalle de runtime o referencia.
3
+ This guide explains the package mental model before going into runtime details or the API reference.
4
4
 
5
- ## 1. Primitivas terminal-first
5
+ ## 1. Terminal-First Primitives
6
6
 
7
- `valyrianjs-terminal` no renderiza HTML ni componentes de navegador. Sus primitivas generan nodos terminales propios que luego se convierten en texto plano o en un frame ANSI.
7
+ `valyrianjs-terminal` does not render HTML or browser components. Its primitives generate their own terminal nodes, which are then converted into plain text or an ANSI frame.
8
8
 
9
- Las piezas base se agrupan asi:
9
+ The core pieces are grouped like this:
10
10
 
11
11
  - layout: `Screen`, `Box`, `View`, `Text`, `Table`, `Row`, `Td`
12
- - interaccion: `Input`, `Button`, `List`, `ScrollView`
12
+ - interaction: `Input`, `Button`, `List`, `ScrollView`
13
13
 
14
- Piensalo como un DSL de interfaces de texto, no como una adaptacion visual del DOM.
14
+ Think of it as a text UI DSL, not as a visual adaptation of the DOM.
15
15
 
16
- ## 2. Dos modos de trabajo
16
+ ## 2. Two Working Modes
17
17
 
18
- Hay dos entrypoints principales:
18
+ There are two main entrypoints:
19
19
 
20
- - `renderTerminal()` para generar texto plano a partir de un arbol terminal
21
- - `mountTerminal()` para crear una sesion interactiva con foco, teclado, mouse y escritura opcional a streams
20
+ - `renderTerminal()` to generate plain text from a terminal tree
21
+ - `mountTerminal()` to create an interactive session with focus, keyboard, mouse, and optional writes to streams
22
22
 
23
- Regla simple:
23
+ Simple rule:
24
24
 
25
- - si solo quieres inspeccionar contenido, usa `renderTerminal()`
26
- - si necesitas interaccion o runtime vivo, usa `mountTerminal()`
25
+ - if you only want to inspect content, use `renderTerminal()`
26
+ - if you need interaction or a live runtime, use `mountTerminal()`
27
27
 
28
- ## 3. El estado vive fuera de la libreria
28
+ ## 3. State Lives Outside the Library
29
29
 
30
- La libreria renderiza lo que tu funcion de UI devuelve con el estado actual. No guarda un store de aplicacion por ti.
30
+ The library renders whatever your UI function returns with the current state. It does not manage an application store for you.
31
31
 
32
- Eso significa que:
32
+ That means:
33
33
 
34
- - tus handlers mutan estado externo
35
- - `mountTerminal()` vuelve a evaluar la funcion de render
36
- - `session.update()` solo hace falta cuando mutaste estado fuera de un handler que ya detona rerender
34
+ - your handlers mutate external state
35
+ - `mountTerminal()` re-evaluates the render function
36
+ - `session.update()` is only needed when you mutated state outside a handler that already triggers a rerender
37
37
 
38
- ## 4. `id` es la llave de la interaccion
38
+ ## 4. `id` Is the Key to Interaction
39
39
 
40
- Los nodos interactivos pueden renderizarse sin `id`, pero pierdes gran parte del control programatico.
40
+ Interactive nodes can render without an `id`, but you lose much of the programmatic control.
41
41
 
42
- Necesitas `id` estable si quieres:
42
+ You need a stable `id` if you want to:
43
43
 
44
- - enfocar con `session.focus(id)`
45
- - activar con `session.click(id)`
46
- - participar de hitboxes por coordenadas
47
- - recibir bien flujos de foco y navegacion
44
+ - focus with `session.focus(id)`
45
+ - activate with `session.click(id)`
46
+ - participate in coordinate-based hitboxes
47
+ - get consistent focus and navigation flows
48
48
 
49
- Recomendacion practica: da `id` a todo `Input`, `Button`, `List` y `ScrollView` que vaya a vivir mas de una prueba trivial.
49
+ Practical recommendation: give an `id` to every `Input`, `Button`, `List`, and `ScrollView` that will live beyond a trivial test.
50
50
 
51
- ## 5. Foco e hitboxes
51
+ ## 5. Focus and Hitboxes
52
52
 
53
- La sesion calcula hitboxes a partir del frame renderizado actual. Eso permite dos clases de interaccion:
53
+ The session computes hitboxes from the current rendered frame. This enables two kinds of interaction:
54
54
 
55
- - por identificador: `focus(id)`, `click(id)`
56
- - por coordenadas: `focusAt(x, y)`, `clickAt(x, y)`
55
+ - by identifier: `focus(id)`, `click(id)`
56
+ - by coordinates: `focusAt(x, y)`, `clickAt(x, y)`
57
57
 
58
- El foco secuencial tambien sale del arbol actual:
58
+ Sequential focus also comes from the current tree:
59
59
 
60
60
  - `focusNext()`
61
61
  - `focusPrev()`
62
62
  - `dispatchKey("TAB")`
63
63
  - `dispatchKey("SHIFT_TAB")`
64
64
 
65
- Si cambia el arbol, cambia tambien el orden y la geometria del foco.
65
+ If the tree changes, focus order and geometry change as well.
66
66
 
67
- ## 6. Salida plana vs salida ANSI
67
+ ## 6. Plain Output vs ANSI Output
68
68
 
69
- El paquete maneja dos representaciones utiles:
69
+ The package works with two useful representations:
70
70
 
71
- - salida plana: la devuelven `renderTerminal()` y `session.output()`
72
- - salida ANSI: la devuelve `session.ansiOutput()` y, si activas `ansi: true`, tambien se escribe a `stdout`
71
+ - plain output: returned by `renderTerminal()` and `session.output()`
72
+ - ANSI output: returned by `session.ansiOutput()` and, if you enable `ansi: true`, also written to `stdout`
73
73
 
74
- Usa salida plana para snapshots y pruebas. Usa ANSI cuando necesitas cursor, spans visuales, foco o integracion con una terminal real.
74
+ Use plain output for snapshots and tests. Use ANSI when you need cursor control, visual spans, focus, or integration with a real terminal.
75
75
 
76
- ## 7. Streams y cleanup
76
+ ## 7. Streams and Cleanup
77
77
 
78
- `mountTerminal()` puede trabajar sin streams, pero si conectas `stdin` y `stdout` la sesion entra en modo runtime real.
78
+ `mountTerminal()` can work without streams, but if you connect `stdin` and `stdout` the session enters real runtime mode.
79
79
 
80
- Cuando montas con `stdin`:
80
+ When you mount with `stdin`:
81
81
 
82
- - la sesion escucha `data`
83
- - intenta activar raw mode si el stream lo soporta
84
- - intenta restaurarlo al llamar `destroy()`
82
+ - the session listens for `data`
83
+ - it tries to enable raw mode if the stream supports it
84
+ - it tries to restore it when you call `destroy()`
85
85
 
86
- Por eso `destroy()` no es opcional cuando conectaste streams reales.
86
+ That is why `destroy()` is not optional when you connect real streams.
87
87
 
88
- ## 8. Donde seguir
88
+ ## 8. Where to Go Next
89
89
 
90
- - `docs/interaction-model.md` explica que hace cada primitiva interactiva
91
- - `docs/session-runtime.md` explica lifecycle, streams, clipboard, coordenadas y mouse
92
- - `docs/cookbook.md` muestra recetas cortas para tareas comunes
93
- - `docs/api-reference.md` sirve como consulta puntual
90
+ - `docs/interaction-model.md` explains what each interactive primitive does
91
+ - `docs/session-runtime.md` explains lifecycle, streams, clipboard, coordinates, and mouse support
92
+ - `docs/cookbook.md` shows short recipes for common tasks
93
+ - `docs/api-reference.md` works as a point reference
package/docs/getting-started.md CHANGED
@@ -1,16 +1,16 @@
1
1
  # Getting Started
2
2
 
3
- Esta guia cubre el happy path minimo para empezar con `valyrianjs-terminal`.
3
+ This guide covers the minimum happy path to get started with `valyrianjs-terminal`.
4
4
 
5
- ## 1. Instala los paquetes
5
+ ## 1. Install the Packages
6
6
 
7
7
  ```bash
8
8
  npm install valyrianjs-terminal valyrian.js
9
9
  ```
10
10
 
11
- ## 2. Empieza con render estatico
11
+ ## 2. Start with Static Rendering
12
12
 
13
- Primero valida layout y contenido sin streams ni runtime interactivo.
13
+ First validate layout and content without streams or the interactive runtime.
14
14
 
15
15
  ```tsx
16
16
  /** @jsx v */
@@ -29,15 +29,15 @@ const output = renderTerminal(
29
29
  console.log(output);
30
30
  ```
31
31
 
32
- Usa este camino cuando quieras:
32
+ Use this path when you want to:
33
33
 
34
- - generar snapshots
35
- - validar layout
36
- - probar salida plana sin conectar `stdin` ni `stdout`
34
+ - generate snapshots
35
+ - validate layout
36
+ - test plain output without connecting `stdin` or `stdout`
37
37
 
38
- ## 3. Sube a una sesion interactiva minima
38
+ ## 3. Move to a Minimal Interactive Session
39
39
 
40
- Cuando ya necesitas editar texto, manejar foco o reaccionar a teclado, cambia a `mountTerminal()`.
40
+ Once you need text editing, focus management, or keyboard handling, switch to `mountTerminal()`.
41
41
 
42
42
  ```tsx
43
43
  /** @jsx v */
@@ -80,11 +80,11 @@ session.dispatchKey("i");
80
80
  console.log(session.output());
81
81
  ```
82
82
 
83
- Regla practica: da `id` estables a `Input`, `Button`, `List` y `ScrollView` si quieres usar foco, coordenadas o interaccion programatica.
83
+ Practical rule: give stable `id` values to `Input`, `Button`, `List`, and `ScrollView` if you want to use focus, coordinates, or programmatic interaction.
84
84
 
85
- ## 4. Entiende el lifecycle minimo
85
+ ## 4. Understand the Minimum Lifecycle
86
86
 
87
- La sesion no guarda tu estado de negocio; vuelve a evaluar la funcion de render con el estado externo actual.
87
+ The session does not store your application state; it re-evaluates the render function with the current external state.
88
88
 
89
89
  ```tsx
90
90
  /** @jsx v */
@@ -108,16 +108,16 @@ console.log(session.output());
108
108
  session.destroy();
109
109
  ```
110
110
 
111
- Resumen rapido:
111
+ Quick summary:
112
112
 
113
- - `output()` devuelve el frame actual en texto plano
114
- - `ansiOutput()` devuelve el frame actual como ANSI completo
115
- - `update()` reevalua la funcion de render
116
- - `destroy()` desmonta listeners y limpia `stdin` cuando aplica
113
+ - `output()` returns the current frame as plain text
114
+ - `ansiOutput()` returns the current frame as full ANSI output
115
+ - `update()` re-evaluates the render function
116
+ - `destroy()` removes listeners and cleans up `stdin` when applicable
117
117
 
118
- ## 5. Cuando conectar streams
118
+ ## 5. When to Connect Streams
119
119
 
120
- Conecta `stdin`, `stdout` y `ansi: true` solo cuando ya vas a correr una UI real en terminal.
120
+ Connect `stdin`, `stdout`, and `ansi: true` only when you are ready to run a real terminal UI.
121
121
 
122
122
  ```tsx
123
123
  /** @jsx v */
@@ -137,9 +137,9 @@ const session = mountTerminal(() => (
137
137
  });
138
138
  ```
139
139
 
140
- Para pruebas o snapshots, normalmente basta con `renderTerminal()` o `mountTerminal()` sin streams.
140
+ For tests or snapshots, `renderTerminal()` or `mountTerminal()` without streams is usually enough.
141
141
 
142
- ## Siguiente lectura
142
+ ## Next Reading
143
143
 
144
144
  - `docs/core-concepts.md`
145
145
  - `docs/interaction-model.md`
package/docs/interaction-model.md CHANGED
@@ -1,33 +1,33 @@
1
1
  # Interaction Model
2
2
 
3
- Esta guia describe como responden las primitivas interactivas del paquete. Si todavia no tienes claro el modelo base, empieza por `docs/core-concepts.md`. Si necesitas lifecycle, streams o runtime de sesion, sigue con `docs/session-runtime.md`.
3
+ This guide describes how the package's interactive primitives respond. If the base model is not clear yet, start with `docs/core-concepts.md`. If you need session lifecycle, streams, or runtime details, continue with `docs/session-runtime.md`.
4
4
 
5
- ## Reglas compartidas
5
+ ## Shared rules
6
6
 
7
- - `Tab` avanza al siguiente elemento enfocable.
8
- - `Shift+Tab` regresa al anterior.
9
- - Los nodos interactivos necesitan `id` si quieres enfocarlos o activarlos programaticamente.
10
- - `focusAt(x, y)` y `clickAt(x, y)` dependen de los hitboxes del frame actual.
7
+ - `Tab` moves to the next focusable element.
8
+ - `Shift+Tab` moves back to the previous one.
9
+ - Interactive nodes need an `id` if you want to focus or activate them programmatically.
10
+ - `focusAt(x, y)` and `clickAt(x, y)` depend on the hitboxes in the current frame.
11
11
 
12
12
  ## `Input`
13
13
 
14
- `Input` es una primitiva de edicion de una sola linea con cursor, seleccion y submit.
14
+ `Input` is a single-line editing primitive with a cursor, selection, and submit support.
15
15
 
16
- Comportamiento observable:
16
+ Observable behavior:
17
17
 
18
- - texto normal: inserta caracteres
19
- - `Enter`: dispara `onsubmit`
20
- - `Left` / `Right`: mueve cursor
21
- - `Shift+Left` / `Shift+Right`: extiende seleccion
22
- - `Alt+Left` / `Alt+Right`: navega por palabra
23
- - `Home` / `End`: salta al inicio o final
24
- - `Ctrl+A`: selecciona todo
25
- - `Ctrl+C`: copia seleccion
26
- - `Ctrl+X`: corta seleccion
27
- - `Ctrl+V`: pega desde clipboard
28
- - `Backspace` / `Delete`: elimina contenido
18
+ - regular text: inserts characters
19
+ - `Enter`: triggers `onsubmit`
20
+ - `Left` / `Right`: moves the cursor
21
+ - `Shift+Left` / `Shift+Right`: extends the selection
22
+ - `Alt+Left` / `Alt+Right`: moves by word
23
+ - `Home` / `End`: jumps to the start or end
24
+ - `Ctrl+A`: selects all
25
+ - `Ctrl+C`: copies the selection
26
+ - `Ctrl+X`: cuts the selection
27
+ - `Ctrl+V`: pastes from the clipboard
28
+ - `Backspace` / `Delete`: removes content
29
29
 
30
- Handlers principales:
30
+ Main handlers:
31
31
 
32
32
  - `onchange`
33
33
  - `oninput`
@@ -36,15 +36,15 @@ Handlers principales:
36
36
 
37
37
  ## `Button`
38
38
 
39
- `Button` representa una accion discreta.
39
+ `Button` represents a discrete action.
40
40
 
41
- Comportamiento observable:
41
+ Observable behavior:
42
42
 
43
- - responde a `Enter` y `Space` cuando tiene foco
44
- - responde a `session.click(id)`
45
- - responde a `session.clickAt(x, y)` cuando el hitbox cae en el boton
43
+ - responds to `Enter` and `Space` when focused
44
+ - responds to `session.click(id)`
45
+ - responds to `session.clickAt(x, y)` when the hitbox lands on the button
46
46
 
47
- Handlers principales:
47
+ Main handlers:
48
48
 
49
49
  - `onpress`
50
50
  - `onclick`
@@ -53,16 +53,16 @@ Handlers principales:
53
53
 
54
54
  ## `List`
55
55
 
56
- `List` modela seleccion y activacion por fila.
56
+ `List` models row selection and activation.
57
57
 
58
- Comportamiento observable:
58
+ Observable behavior:
59
59
 
60
- - `Up` / `Left`: mueve seleccion hacia arriba
61
- - `Down` / `Right`: mueve seleccion hacia abajo
62
- - `Enter`: dispara `onpress`
63
- - el hover por mouse expone fila, indice y valor actual
60
+ - `Up` / `Left`: moves selection up
61
+ - `Down` / `Right`: moves selection down
62
+ - `Enter`: triggers `onpress`
63
+ - mouse hover exposes the current row, index, and value
64
64
 
65
- Handlers principales:
65
+ Main handlers:
66
66
 
67
67
  - `onchange`
68
68
  - `onpress`
@@ -72,21 +72,21 @@ Handlers principales:
72
72
  - `oncapturestart`
73
73
  - `oncaptureend`
74
74
 
75
- Con `pointerCapture`, la lista conserva la interaccion durante drag aunque el puntero salga del hitbox inicial.
75
+ With `pointerCapture`, the list keeps the interaction during a drag even if the pointer leaves the initial hitbox.
76
76
 
77
77
  ## `ScrollView`
78
78
 
79
- `ScrollView` recorta contenido vertical y expone interaccion por viewport.
79
+ `ScrollView` clips vertical content and exposes viewport-based interaction.
80
80
 
81
- Comportamiento observable:
81
+ Observable behavior:
82
82
 
83
- - `Up`: desplaza hacia arriba
84
- - `Down`: desplaza hacia abajo
85
- - `height`: define el viewport visible
86
- - `highlightRows`: resalta filas visibles concretas
87
- - el hover por mouse expone fila visible y texto renderizado
83
+ - `Up`: scrolls up
84
+ - `Down`: scrolls down
85
+ - `height`: defines the visible viewport
86
+ - `highlightRows`: highlights specific visible rows
87
+ - mouse hover exposes the visible row and rendered text
88
88
 
89
- Handlers principales:
89
+ Main handlers:
90
90
 
91
91
  - `onhover`
92
92
  - `onrowenter`
@@ -94,22 +94,22 @@ Handlers principales:
94
94
  - `oncapturestart`
95
95
  - `oncaptureend`
96
96
 
97
- Con `pointerCapture`, el scroll mantiene la interaccion durante drag aunque el puntero salga del viewport.
97
+ With `pointerCapture`, scrolling keeps the interaction during a drag even if the pointer leaves the viewport.
98
98
 
99
- ## Mouse y pointer capture
99
+ ## Mouse and pointer capture
100
100
 
101
- Cuando la sesion recibe eventos SGR de mouse:
101
+ When the session receives SGR mouse events:
102
102
 
103
- - `press`: enfoca y activa el hitbox correspondiente
104
- - `drag`: extiende seleccion en `Input` o actualiza hover en `List` y `ScrollView`
105
- - `release`: cierra captura y limpia hover cuando corresponde
106
- - `wheel-up` / `wheel-down`: se traducen a navegacion vertical
103
+ - `press`: focuses and activates the matching hitbox
104
+ - `drag`: extends selection in `Input` or updates hover in `List` and `ScrollView`
105
+ - `release`: ends capture and clears hover when needed
106
+ - `wheel-up` / `wheel-down`: translate to vertical navigation
107
107
 
108
- `pointerCapture` solo aplica hoy a `List` y `ScrollView`.
108
+ `pointerCapture` currently applies only to `List` and `ScrollView`.
109
109
 
110
- ## Donde seguir
110
+ ## Where to go next
111
111
 
112
- - `docs/core-concepts.md` para el modelo mental del paquete
113
- - `docs/session-runtime.md` para lifecycle, streams, clipboard y runtime
114
- - `docs/cookbook.md` para recetas practicas
115
- - `docs/api-reference.md` para consulta puntual de props, payloads y tipos
112
+ - `docs/core-concepts.md` for the package mental model
113
+ - `docs/session-runtime.md` for lifecycle, streams, clipboard, and runtime
114
+ - `docs/cookbook.md` for practical recipes
115
+ - `docs/api-reference.md` for quick lookup of props, payloads, and types
package/docs/local-demo.md CHANGED
@@ -1,14 +1,14 @@
1
1
  # Local Demo
2
2
 
3
- `examples/` existe solo como apoyo de desarrollo local. No forma parte del paquete publicado por npm, no aparece en `exports` y no hay CLI publicada por `valyrianjs-terminal`.
3
+ `examples/` exists only to support local development. It is not part of the package published to npm, it does not appear in `exports`, and `valyrianjs-terminal` does not publish a CLI.
4
4
 
5
- ## Archivos
5
+ ## Files
6
6
 
7
- - `examples/demo.tsx`: define `createDemoState()` y `DemoApp`; valida composicion de primitivas (`Screen`, `Box`, `View`, `Text`, `Input`, `Button`, `List`, `ScrollView`, `Table`, `Row`, `Td`) y payloads basicos de eventos.
8
- - `examples/basic.tsx`: valida el camino minimo para usar `renderTerminal()` en snapshot y `mountTerminal()` con `stdin`/`stdout` en local.
9
- - `examples/cli.tsx`: valida el launcher local con `--help`, `--snapshot`, foco inicial, salida por `Esc` o `Ctrl+C` y cleanup ANSI al cerrar.
7
+ - `examples/demo.tsx`: defines `createDemoState()` and `DemoApp`; validates primitive composition (`Screen`, `Box`, `View`, `Text`, `Input`, `Button`, `List`, `ScrollView`, `Table`, `Row`, `Td`) and basic event payloads.
8
+ - `examples/basic.tsx`: validates the minimum path for using `renderTerminal()` in snapshot mode and `mountTerminal()` with local `stdin`/`stdout`.
9
+ - `examples/cli.tsx`: validates the local launcher with `--help`, `--snapshot`, initial focus, exit via `Esc` or `Ctrl+C`, and ANSI cleanup on close.
10
10
 
11
- ## Comandos
11
+ ## Commands
12
12
 
13
13
  ```bash
14
14
  bun run examples/basic.tsx
@@ -21,8 +21,8 @@ bun run typecheck
21
21
  bun run build
22
22
  ```
23
23
 
24
- ## Alcance
24
+ ## Scope
25
25
 
26
- - `--snapshot` imprime la UI de ejemplo como texto plano.
27
- - sin `--snapshot`, los ejemplos montan una sesion local conectada a `process.stdin` y `process.stdout`.
28
- - estos archivos no son una interfaz distribuida a consumidores del paquete; son fixtures manuales para validar el adapter en la maquina local.
26
+ - `--snapshot` prints the example UI as plain text.
27
+ - without `--snapshot`, the examples mount a local session connected to `process.stdin` and `process.stdout`.
28
+ - these files are not a distributed interface for package consumers; they are manual fixtures for validating the adapter on a local machine.