@valyrianjs/terminal 0.1.0

package/docs/cookbook.md

@@ -0,0 +1,286 @@
+# Cookbook
+
+Recetas cortas y copiables para `valyrianjs-terminal`. Esta guia complementa `docs/getting-started.md`, `docs/interaction-model.md` y `docs/api-reference.md`.
+
+## Render estatico para snapshots
+
+Usalo cuando quieras validar layout o generar texto plano sin abrir una sesion interactiva.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+import { Screen, Text, renderTerminal } from "valyrianjs-terminal";
+
+const output = renderTerminal(
+  <Screen title="Snapshot Demo">
+    <Text>Hello terminal</Text>
+    <Text>Status: ok</Text>
+  </Screen>
+);
+
+console.log(output);
+```
+
+## Input controlado con submit
+
+Usalo cuando necesites un campo editable que guarde el valor final al presionar `Enter`.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+import { Input, Screen, Text, mountTerminal } from "valyrianjs-terminal";
+
+const state = { value: "", submitted: "" };
+
+const session = mountTerminal(() => (
+  <Screen>
+    <Input
+      id="name"
+      value={state.value}
+      placeholder="Write a quick note"
+      onchange={(event) => {
+        state.value = event.value;
+      }}
+      onsubmit={(event) => {
+        state.submitted = event.value;
+      }}
+    />
+    <Text>{state.submitted || "Nothing submitted yet"}</Text>
+  </Screen>
+));
+
+session.focus("name");
+session.dispatchKey("H");
+session.dispatchKey("i");
+session.dispatchKey("ENTER");
+
+console.log(state.submitted);
+console.log(session.output());
+```
+
+## Boton que muta estado
+
+Usalo cuando quieras activar acciones simples desde teclado o click programatico.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+import { Button, Screen, Text, mountTerminal } from "valyrianjs-terminal";
+
+const state = { count: 0 };
+
+const session = mountTerminal(() => (
+  <Screen>
+    <Button
+      id="increment"
+      onpress={() => {
+        state.count += 1;
+      }}
+    >
+      Increment
+    </Button>
+    <Text>{`Count: ${state.count}`}</Text>
+  </Screen>
+));
+
+session.click("increment");
+session.click("increment");
+
+console.log(session.output());
+```
+
+## Lista interactiva con `onchange` y `onpress`
+
+Usalo cuando quieras separar el item actualmente seleccionado del item activado con `Enter`.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+import { List, Screen, Text, mountTerminal } from "valyrianjs-terminal";
+
+const state = { selected: "", opened: "" };
+
+const session = mountTerminal(() => (
+  <Screen>
+    <List
+      id="menu"
+      items={["Inbox", "Today", "Done"]}
+      onchange={(event) => {
+        state.selected = event.value;
+      }}
+      onpress={(event) => {
+        state.opened = event.value;
+      }}
+    />
+    <Text>{`Selected: ${state.selected || "-"}`}</Text>
+    <Text>{`Opened: ${state.opened || "-"}`}</Text>
+  </Screen>
+));
+
+session.focus("menu");
+session.dispatchKey("DOWN");
+session.dispatchKey("DOWN");
+session.dispatchKey("ENTER");
+
+console.log(state.selected);
+console.log(state.opened);
+```
+
+## Scroll view con `height` y `highlightRows`
+
+Usalo para recortar contenido vertical y marcar filas relevantes dentro del viewport.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+import { Screen, ScrollView, Text, mountTerminal } from "valyrianjs-terminal";
+
+const session = mountTerminal(() => (
+  <Screen>
+    <ScrollView id="activity" height={3} highlightRows={[2]}>
+      <Text>Alpha</Text>
+      <Text>Beta</Text>
+      <Text>Gamma</Text>
+      <Text>Delta</Text>
+    </ScrollView>
+  </Screen>
+), { ansi: true });
+
+session.focus("activity");
+console.log(session.output());
+
+session.dispatchKey("DOWN");
+console.log(session.output());
+console.log(session.ansiOutput());
+```
+
+## Clipboard adapter custom
+
+Usalo cuando quieras conectar copiar y pegar con un portapapeles propio en lugar del estado interno de la sesion.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+import { Input, Screen, mountTerminal } from "valyrianjs-terminal";
+
+const state = { value: "abcd" };
+const clipboard = {
+  value: "",
+  readText() {
+    return this.value;
+  },
+  writeText(value: string) {
+    this.value = value;
+  }
+};
+
+const session = mountTerminal(() => (
+  <Screen>
+    <Input
+      id="name"
+      value={state.value}
+      onchange={(event) => {
+        state.value = event.value;
+      }}
+    />
+  </Screen>
+), { clipboard });
+
+session.focus("name");
+session.dispatchKey("HOME");
+session.dispatchKey("SHIFT_RIGHT");
+session.dispatchKey("SHIFT_RIGHT");
+session.dispatchKey("CTRL_C");
+
+clipboard.value = "XY";
+session.dispatchKey("END");
+session.dispatchKey("CTRL_V");
+
+console.log(session.clipboard());
+console.log(state.value);
+```
+
+## Interaccion por coordenadas con `focusAt` y `clickAt`
+
+Usalo en pruebas o adapters donde el punto de entrada real son coordenadas del frame y no ids conocidos.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+import { Button, Input, Screen, mountTerminal } from "valyrianjs-terminal";
+
+const state = { clicks: 0 };
+
+const session = mountTerminal(() => (
+  <Screen>
+    <Input id="name" value="abc" />
+    <Button id="save" onpress={() => {
+      state.clicks += 1;
+    }}>
+      Save
+    </Button>
+  </Screen>
+));
+
+session.focusAt(2, 1);
+session.clickAt(3, 2);
+
+console.log(session.output());
+console.log(state.clicks);
+```
+
+## Inspeccion de salida ANSI con `ansiOutput`
+
+Usalo cuando necesites verificar cursor, estilos o secuencias ANSI en pruebas e integraciones.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+import { Input, Screen, mountTerminal } from "valyrianjs-terminal";
+
+const state = { value: "AB" };
+
+const session = mountTerminal(() => (
+  <Screen title="ANSI Demo">
+    <Input
+      id="name"
+      value={state.value}
+      onchange={(event) => {
+        state.value = event.value;
+      }}
+    />
+  </Screen>
+), { ansi: true });
+
+session.focus("name");
+session.dispatchKey("LEFT");
+
+const ansi = session.ansiOutput();
+
+console.log(ansi);
+console.log(/\u001b\[[0-9]+;[0-9]+H/.test(ansi));
+```
+
+## Ver tambien
+
+- `docs/getting-started.md` para el flujo minimo de montaje
+- `docs/core-concepts.md` para el modelo mental del paquete
+- `docs/interaction-model.md` para foco, teclado, mouse y clipboard
+- `docs/session-runtime.md` para lifecycle, streams y runtime de sesion
+- `docs/api-reference.md` para la superficie publica completa

package/docs/core-concepts.md

@@ -0,0 +1,93 @@
+# Core Concepts
+
+Esta guia explica el modelo mental del paquete antes de entrar al detalle de runtime o referencia.
+
+## 1. Primitivas terminal-first
+
+`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.
+
+Las piezas base se agrupan asi:
+
+- layout: `Screen`, `Box`, `View`, `Text`, `Table`, `Row`, `Td`
+- interaccion: `Input`, `Button`, `List`, `ScrollView`
+
+Piensalo como un DSL de interfaces de texto, no como una adaptacion visual del DOM.
+
+## 2. Dos modos de trabajo
+
+Hay dos entrypoints principales:
+
+- `renderTerminal()` para generar texto plano a partir de un arbol terminal
+- `mountTerminal()` para crear una sesion interactiva con foco, teclado, mouse y escritura opcional a streams
+
+Regla simple:
+
+- si solo quieres inspeccionar contenido, usa `renderTerminal()`
+- si necesitas interaccion o runtime vivo, usa `mountTerminal()`
+
+## 3. El estado vive fuera de la libreria
+
+La libreria renderiza lo que tu funcion de UI devuelve con el estado actual. No guarda un store de aplicacion por ti.
+
+Eso significa que:
+
+- tus handlers mutan estado externo
+- `mountTerminal()` vuelve a evaluar la funcion de render
+- `session.update()` solo hace falta cuando mutaste estado fuera de un handler que ya detona rerender
+
+## 4. `id` es la llave de la interaccion
+
+Los nodos interactivos pueden renderizarse sin `id`, pero pierdes gran parte del control programatico.
+
+Necesitas `id` estable si quieres:
+
+- enfocar con `session.focus(id)`
+- activar con `session.click(id)`
+- participar de hitboxes por coordenadas
+- recibir bien flujos de foco y navegacion
+
+Recomendacion practica: da `id` a todo `Input`, `Button`, `List` y `ScrollView` que vaya a vivir mas de una prueba trivial.
+
+## 5. Foco e hitboxes
+
+La sesion calcula hitboxes a partir del frame renderizado actual. Eso permite dos clases de interaccion:
+
+- por identificador: `focus(id)`, `click(id)`
+- por coordenadas: `focusAt(x, y)`, `clickAt(x, y)`
+
+El foco secuencial tambien sale del arbol actual:
+
+- `focusNext()`
+- `focusPrev()`
+- `dispatchKey("TAB")`
+- `dispatchKey("SHIFT_TAB")`
+
+Si cambia el arbol, cambia tambien el orden y la geometria del foco.
+
+## 6. Salida plana vs salida ANSI
+
+El paquete maneja dos representaciones utiles:
+
+- salida plana: la devuelven `renderTerminal()` y `session.output()`
+- salida ANSI: la devuelve `session.ansiOutput()` y, si activas `ansi: true`, tambien se escribe a `stdout`
+
+Usa salida plana para snapshots y pruebas. Usa ANSI cuando necesitas cursor, spans visuales, foco o integracion con una terminal real.
+
+## 7. Streams y cleanup
+
+`mountTerminal()` puede trabajar sin streams, pero si conectas `stdin` y `stdout` la sesion entra en modo runtime real.
+
+Cuando montas con `stdin`:
+
+- la sesion escucha `data`
+- intenta activar raw mode si el stream lo soporta
+- intenta restaurarlo al llamar `destroy()`
+
+Por eso `destroy()` no es opcional cuando conectaste streams reales.
+
+## 8. Donde seguir
+
+- `docs/interaction-model.md` explica que hace cada primitiva interactiva
+- `docs/session-runtime.md` explica lifecycle, streams, clipboard, coordenadas y mouse
+- `docs/cookbook.md` muestra recetas cortas para tareas comunes
+- `docs/api-reference.md` sirve como consulta puntual

package/docs/getting-started.md

@@ -0,0 +1,148 @@
+# Getting Started
+
+Esta guia cubre el happy path minimo para empezar con `valyrianjs-terminal`.
+
+## 1. Instala los paquetes
+
+```bash
+npm install valyrianjs-terminal valyrian.js
+```
+
+## 2. Empieza con render estatico
+
+Primero valida layout y contenido sin streams ni runtime interactivo.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+import { Screen, Text, renderTerminal } from "valyrianjs-terminal";
+
+const output = renderTerminal(
+  <Screen title="Status">
+    <Text>Hello terminal</Text>
+    <Text>Status: ok</Text>
+  </Screen>
+);
+
+console.log(output);
+```
+
+Usa este camino cuando quieras:
+
+- generar snapshots
+- validar layout
+- probar salida plana sin conectar `stdin` ni `stdout`
+
+## 3. Sube a una sesion interactiva minima
+
+Cuando ya necesitas editar texto, manejar foco o reaccionar a teclado, cambia a `mountTerminal()`.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+import { Button, Input, Screen, Text, mountTerminal } from "valyrianjs-terminal";
+
+const state = { value: "", saved: "" };
+
+const session = mountTerminal(() => (
+  <Screen title="Quick Note">
+    <Input
+      id="note"
+      value={state.value}
+      placeholder="Write a quick note"
+      onchange={(event) => {
+        state.value = event.value;
+      }}
+      onsubmit={(event) => {
+        state.saved = event.value;
+      }}
+    />
+    <Button
+      id="save"
+      onpress={() => {
+        state.saved = state.value;
+      }}
+    >
+      Save
+    </Button>
+    <Text>{state.saved || "Nothing saved yet"}</Text>
+  </Screen>
+));
+
+session.focus("note");
+session.dispatchKey("H");
+session.dispatchKey("i");
+
+console.log(session.output());
+```
+
+Regla practica: da `id` estables a `Input`, `Button`, `List` y `ScrollView` si quieres usar foco, coordenadas o interaccion programatica.
+
+## 4. Entiende el lifecycle minimo
+
+La sesion no guarda tu estado de negocio; vuelve a evaluar la funcion de render con el estado externo actual.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+import { Screen, Text, mountTerminal } from "valyrianjs-terminal";
+
+const state = { count: 0 };
+
+const session = mountTerminal(() => (
+  <Screen>
+    <Text>Count: {state.count}</Text>
+  </Screen>
+));
+
+state.count += 1;
+session.update();
+
+console.log(session.output());
+session.destroy();
+```
+
+Resumen rapido:
+
+- `output()` devuelve el frame actual en texto plano
+- `ansiOutput()` devuelve el frame actual como ANSI completo
+- `update()` reevalua la funcion de render
+- `destroy()` desmonta listeners y limpia `stdin` cuando aplica
+
+## 5. Cuando conectar streams
+
+Conecta `stdin`, `stdout` y `ansi: true` solo cuando ya vas a correr una UI real en terminal.
+
+```tsx
+/** @jsx v */
+/** @jsxFrag v.fragment */
+
+import { v } from "valyrian.js";
+import { Screen, Text, mountTerminal } from "valyrianjs-terminal";
+
+const session = mountTerminal(() => (
+  <Screen title="Live App">
+    <Text>Streaming to the terminal</Text>
+  </Screen>
+), {
+  stdin: process.stdin,
+  stdout: process.stdout,
+  ansi: true
+});
+```
+
+Para pruebas o snapshots, normalmente basta con `renderTerminal()` o `mountTerminal()` sin streams.
+
+## Siguiente lectura
+
+- `docs/core-concepts.md`
+- `docs/interaction-model.md`
+- `docs/session-runtime.md`
+- `docs/cookbook.md`
+- `docs/api-reference.md`

package/docs/interaction-model.md

@@ -0,0 +1,115 @@
+# Interaction Model
+
+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`.
+
+## Reglas compartidas
+
+- `Tab` avanza al siguiente elemento enfocable.
+- `Shift+Tab` regresa al anterior.
+- Los nodos interactivos necesitan `id` si quieres enfocarlos o activarlos programaticamente.
+- `focusAt(x, y)` y `clickAt(x, y)` dependen de los hitboxes del frame actual.
+
+## `Input`
+
+`Input` es una primitiva de edicion de una sola linea con cursor, seleccion y submit.
+
+Comportamiento observable:
+
+- texto normal: inserta caracteres
+- `Enter`: dispara `onsubmit`
+- `Left` / `Right`: mueve cursor
+- `Shift+Left` / `Shift+Right`: extiende seleccion
+- `Alt+Left` / `Alt+Right`: navega por palabra
+- `Home` / `End`: salta al inicio o final
+- `Ctrl+A`: selecciona todo
+- `Ctrl+C`: copia seleccion
+- `Ctrl+X`: corta seleccion
+- `Ctrl+V`: pega desde clipboard
+- `Backspace` / `Delete`: elimina contenido
+
+Handlers principales:
+
+- `onchange`
+- `oninput`
+- `onsubmit`
+- `onChangeText`
+
+## `Button`
+
+`Button` representa una accion discreta.
+
+Comportamiento observable:
+
+- responde a `Enter` y `Space` cuando tiene foco
+- responde a `session.click(id)`
+- responde a `session.clickAt(x, y)` cuando el hitbox cae en el boton
+
+Handlers principales:
+
+- `onpress`
+- `onclick`
+- `action`
+- `onPress`
+
+## `List`
+
+`List` modela seleccion y activacion por fila.
+
+Comportamiento observable:
+
+- `Up` / `Left`: mueve seleccion hacia arriba
+- `Down` / `Right`: mueve seleccion hacia abajo
+- `Enter`: dispara `onpress`
+- el hover por mouse expone fila, indice y valor actual
+
+Handlers principales:
+
+- `onchange`
+- `onpress`
+- `onhover`
+- `onrowenter`
+- `onrowleave`
+- `oncapturestart`
+- `oncaptureend`
+
+Con `pointerCapture`, la lista conserva la interaccion durante drag aunque el puntero salga del hitbox inicial.
+
+## `ScrollView`
+
+`ScrollView` recorta contenido vertical y expone interaccion por viewport.
+
+Comportamiento observable:
+
+- `Up`: desplaza hacia arriba
+- `Down`: desplaza hacia abajo
+- `height`: define el viewport visible
+- `highlightRows`: resalta filas visibles concretas
+- el hover por mouse expone fila visible y texto renderizado
+
+Handlers principales:
+
+- `onhover`
+- `onrowenter`
+- `onrowleave`
+- `oncapturestart`
+- `oncaptureend`
+
+Con `pointerCapture`, el scroll mantiene la interaccion durante drag aunque el puntero salga del viewport.
+
+## Mouse y pointer capture
+
+Cuando la sesion recibe eventos SGR de mouse:
+
+- `press`: enfoca y activa el hitbox correspondiente
+- `drag`: extiende seleccion en `Input` o actualiza hover en `List` y `ScrollView`
+- `release`: cierra captura y limpia hover cuando corresponde
+- `wheel-up` / `wheel-down`: se traducen a navegacion vertical
+
+`pointerCapture` solo aplica hoy a `List` y `ScrollView`.
+
+## Donde seguir
+
+- `docs/core-concepts.md` para el modelo mental del paquete
+- `docs/session-runtime.md` para lifecycle, streams, clipboard y runtime
+- `docs/cookbook.md` para recetas practicas
+- `docs/api-reference.md` para consulta puntual de props, payloads y tipos

package/docs/local-demo.md

@@ -0,0 +1,28 @@
+# Local Demo
+
+`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`.
+
+## Archivos
+
+- `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.
+- `examples/basic.tsx`: valida el camino minimo para usar `renderTerminal()` en snapshot y `mountTerminal()` con `stdin`/`stdout` en local.
+- `examples/cli.tsx`: valida el launcher local con `--help`, `--snapshot`, foco inicial, salida por `Esc` o `Ctrl+C` y cleanup ANSI al cerrar.
+
+## Comandos
+
+```bash
+bun run examples/basic.tsx
+bun run examples/basic.tsx --snapshot
+bun run examples/cli.tsx
+bun run examples/cli.tsx --snapshot
+bun run examples/cli.tsx --help
+bun run test
+bun run typecheck
+bun run build
+```
+
+## Alcance
+
+- `--snapshot` imprime la UI de ejemplo como texto plano.
+- sin `--snapshot`, los ejemplos montan una sesion local conectada a `process.stdin` y `process.stdout`.
+- estos archivos no son una interfaz distribuida a consumidores del paquete; son fixtures manuales para validar el adapter en la maquina local.