@valyrianjs/terminal 0.1.0 → 0.1.1

package/README.md

@@ -1,26 +1,26 @@
 # valyrianjs-terminal
 
-Adapter terminal-first para `valyrian.js`. Sirve para renderizar pantallas de texto con primitivas propias y, si lo necesitas, montar sesiones interactivas sobre `stdin` y `stdout`.
+Terminal-first adapter for `valyrian.js`. It lets you render text UIs with its own primitives and, when needed, mount interactive sessions on top of `stdin` and `stdout`.
 
-## Que resuelve
+## What It Solves
 
-- layout terminal-first con `Screen`, `Box`, `View`, `Text`, `Table`, `Row` y `Td`
-- primitivas interactivas con `Input`, `Button`, `List` y `ScrollView`
-- render estatico a texto con `renderTerminal()`
-- runtime interactivo con `mountTerminal()`
+- terminal-first layout with `Screen`, `Box`, `View`, `Text`, `Table`, `Row`, and `Td`
+- interactive primitives with `Input`, `Button`, `List`, and `ScrollView`
+- static text rendering with `renderTerminal()`
+- interactive runtime with `mountTerminal()`
 
-## Instalacion
+## Installation
 
 ```bash
 npm install valyrianjs-terminal valyrian.js
 ```
 
-## Elige el entrypoint correcto
+## Choose the Right Entrypoint
 
-- Usa `renderTerminal()` para snapshots, pruebas o salidas no interactivas.
-- Usa `mountTerminal()` cuando necesitas foco, teclado, mouse, clipboard o escritura a `stdout`.
+- Use `renderTerminal()` for snapshots, tests, or non-interactive output.
+- Use `mountTerminal()` when you need focus, keyboard, mouse, clipboard, or writes to `stdout`.
 
-## Ejemplo minimo
+## Minimal Example
 
 ```tsx
 /** @jsx v */
@@ -48,21 +48,21 @@ const session = mountTerminal(() => (
 session.focus("note");
 ```
 
-## Mapa de docs
+## Docs Map
 
-- `docs/getting-started.md` - primer flujo completo, de render estatico a sesion interactiva
-- `docs/core-concepts.md` - modelo mental: ids, foco, hitboxes, salida plana, ANSI y cleanup
-- `docs/interaction-model.md` - comportamiento por primitiva y eventos de interaccion
-- `docs/session-runtime.md` - lifecycle de sesion, streams, clipboard, coordenadas y runtime
-- `docs/cookbook.md` - recetas cortas para tareas concretas
-- `docs/api-reference.md` - referencia de la superficie publica y subpaths publicados
-- `docs/local-demo.md` - demo repo-local, no parte del paquete publicado
+- `docs/getting-started.md` - first complete flow, from static rendering to an interactive session
+- `docs/core-concepts.md` - mental model: ids, focus, hitboxes, plain output, ANSI, and cleanup
+- `docs/interaction-model.md` - behavior of each primitive and interaction events
+- `docs/session-runtime.md` - session lifecycle, streams, clipboard, coordinates, and runtime
+- `docs/cookbook.md` - short recipes for concrete tasks
+- `docs/api-reference.md` - reference for the public surface and published subpaths
+- `docs/local-demo.md` - repo-local demo, not part of the published package
 
-## Alcance del paquete publicado
+## Published Package Scope
 
-El paquete publicado incluye el adapter compilado en `dist/`, esta documentacion y metadatos de soporte. Los archivos de `examples/` viven solo en el repo y no forman parte del paquete distribuido.
+The published package includes the compiled adapter in `dist/`, this documentation, and supporting metadata. Files in `examples/` live only in the repo and are not part of the distributed package.
 
-## Desarrollo local
+## Local Development
 
 ```bash
 bun test

package/docs/api-reference.md

@@ -1,78 +1,78 @@
 # API Reference
 
-Referencia de la superficie publica real publicada por `valyrianjs-terminal`.
+Reference for the actual public surface published by `valyrianjs-terminal`.
 
-## Entrypoints publicados
+## Published Entrypoints
 
 ### `valyrianjs-terminal`
 
-Entrada principal. Expone a alto nivel:
+Main entrypoint. At a high level, it exposes:
 
 - `renderTerminal()`
 - `mountTerminal()`
-- primitivas `Screen`, `Box`, `View`, `Text`, `Input`, `Button`, `ScrollView`, `List`, `Table`, `Row`, `Td`
-- tipos de props, eventos, nodos y sesion
+- primitives `Screen`, `Box`, `View`, `Text`, `Input`, `Button`, `ScrollView`, `List`, `Table`, `Row`, `Td`
+- prop, event, node, and session types
 
 ### `valyrianjs-terminal/render`
 
-Subpath publicado para utilidades de render de bajo nivel.
+Published subpath for lower-level rendering utilities.
 
 - `renderTerminal(input): string`
 - `renderTerminalNode(node): string`
 - `renderTerminalFrame(node): TerminalFrame`
 
-Usa este subpath cuando solo necesites transformar nodos terminales a texto o `TerminalFrame`, sin montar una sesion interactiva.
+Use this subpath when you only need to transform terminal nodes into text or a `TerminalFrame`, without mounting an interactive session.
 
-## Funciones principales
+## Main Functions
 
 ### `renderTerminal(input): string`
 
-Resuelve la raiz recibida y devuelve la salida terminal en texto plano.
+Resolves the provided root and returns terminal output as plain text.
 
-Casos de uso respaldados por la implementacion actual:
+Use cases supported by the current implementation:
 
-- snapshots y pruebas
-- validacion de layout sin `stdin` ni `stdout`
-- inspeccion de contenido en modo no interactivo
+- snapshots and tests
+- layout validation without `stdin` or `stdout`
+- content inspection in non-interactive mode
 
-Notas:
+Notes:
 
-- concatena los nodos raiz con saltos de linea
-- elimina solo el whitespace final con `trimEnd()`
-- no crea listeners ni estado interactivo
+- concatenates root nodes with newlines
+- removes only trailing whitespace with `trimEnd()`
+- does not create listeners or interactive state
 
 ### `mountTerminal(input, options?): TerminalSession`
 
-Monta una sesion interactiva sobre el arbol terminal y devuelve un `TerminalSession`.
+Mounts an interactive session on the terminal tree and returns a `TerminalSession`.
 
-Comportamiento de alto nivel:
+High-level behavior:
 
-- resuelve el arbol actual y lo rerenderiza con `session.update()`
-- administra foco por `id`
-- procesa teclado, mouse, seleccion y clipboard
-- puede escribir automaticamente a `stdout` si se provee
-- si recibe `stdin`, activa raw mode al montar y lo revierte en `destroy()`
+- resolves the current tree and re-renders it with `session.update()`
+- manages focus by `id`
+- handles keyboard, mouse, selection, and clipboard interaction
+- can write to `stdout` automatically when provided
+- if it receives `stdin`, it enables raw mode on mount and restores it in `destroy()`
 
 ## `TerminalMountOptions`
 
-- `ansi?: boolean` - si hay `stdout`, escribe diffs ANSI en vez de texto plano
-- `clipboard?: TerminalClipboardAdapter | false` - adapter custom o desactiva el clipboard del sistema
-- `stdin?` - stream con `on("data")`; `off()`, `removeListener()`, `setRawMode()`, `resume()` y `pause()` son opcionales
-- `stdout?` - writer con `write(chunk: string)`
+- `ansi?: boolean` - if `stdout` is present, writes ANSI diffs instead of plain text
+- `clipboard?: TerminalClipboardAdapter | false` - custom adapter or disables the system clipboard
+- `stdin?` - stream with `on("data")`; `off()`, `removeListener()`, `setRawMode()`, `resume()`, and `pause()` are optional
+- `stdout?` - writer with `write(chunk: string)`
 
-## Primitivas de layout
+## Layout Primitives
 
 ### `Screen`
 
-Props de `TerminalScreenProps`:
+`TerminalScreenProps` props:
 
 - `title?: string`
 
-Funcion: contenedor raiz. Si `title` existe, se renderiza como primera linea del frame.
+Role: root container. If `title` exists, it renders as the first line of the frame.
 
 ### `Box`
 
-Props de `TerminalBoxProps`:
+`TerminalBoxProps` props:
 
 - `direction?: "row" | "column"`
 - `gap?: number`
@@ -83,56 +83,56 @@ Props de `TerminalBoxProps`:
 - `id?: string`
 - `focusable?: boolean`
 
-Funcion: contenedor de layout. En `row` compone horizontalmente; en `column`, verticalmente.
+Role: layout container. In `row`, it composes horizontally; in `column`, vertically.
 
 ### `View`
 
-Props de `TerminalViewProps`:
+`TerminalViewProps` props:
 
-- todas las props de layout de `Box`
+- all layout props from `Box`
 - `role?: string`
 
-Funcion: contenedor semantico equivalente a `terminal-view`.
+Role: semantic container equivalent to `terminal-view`.
 
 ### `Text`
 
-Props de `TerminalTextProps`:
+`TerminalTextProps` props:
 
 - `value?: any`
 
-Funcion: renderiza `value` o el texto concatenado de sus hijos. Si hay saltos de linea, se preservan.
+Role: renders `value` or the concatenated text from its children. If there are line breaks, they are preserved.
 
 ### `Table`
 
-Props de `TerminalTableProps`:
+`TerminalTableProps` props:
 
 - `v-for?: any[]`
 
-Funcion: compone filas y calcula automaticamente el ancho maximo por columna.
+Role: composes rows and automatically calculates the maximum width for each column.
 
 ### `Row`
 
-Props de `TerminalRowProps`:
+`TerminalRowProps` props:
 
 - `separator?: string`
 
-Funcion: une celdas usando `separator` o `" | "` por default.
+Role: joins cells using `separator` or `" | "` by default.
 
 ### `Td`
 
-Props de `TerminalTdProps`:
+`TerminalTdProps` props:
 
 - `padding?: number`
 
-Funcion: envuelve el contenido de la celda y aplica padding interno si se define.
+Role: wraps cell content and applies internal padding when defined.
 
-## Primitivas interactivas
+## Interactive Primitives
 
-Todas dependen de `id` para participar completamente en foco, hitboxes, busqueda por coordenadas y varios helpers de `TerminalSession`.
+All of them depend on `id` to fully participate in focus, hitboxes, coordinate lookup, and several `TerminalSession` helpers.
 
 ### `Input`
 
-Props de `TerminalInputProps`:
+`TerminalInputProps` props:
 
 - `id?: string`
 - `focusable?: boolean`
@@ -143,22 +143,22 @@ Props de `TerminalInputProps`:
 - `onsubmit?(event)`
 - `onChangeText?(value)`
 
-Soporte actual de interaccion:
+Current interaction support:
 
-- cursor y seleccion de texto
+- cursor movement and text selection
 - `LEFT`, `RIGHT`, `SHIFT_LEFT`, `SHIFT_RIGHT`
 - `ALT_LEFT`, `ALT_RIGHT`, `HOME`, `END`
 - `CTRL_A`, `CTRL_C`, `CTRL_X`, `CTRL_V`
-- `BACKSPACE`, `DELETE`, escritura de caracteres y `ENTER`
+- `BACKSPACE`, `DELETE`, character input, and `ENTER`
 
-Payloads importantes:
+Important payloads:
 
 - `TerminalInputChangeEventPayload` - `{ type: "change" | "input", id, value }`
 - `TerminalInputSubmitEventPayload` - `{ type: "submit", id, value }`
 
 ### `Button`
 
-Props de `TerminalButtonProps`:
+`TerminalButtonProps` props:
 
 - `id?: string`
 - `focusable?: boolean`
@@ -168,19 +168,19 @@ Props de `TerminalButtonProps`:
 - `action?(event)`
 - `onPress?(event)`
 
-Activacion actual:
+Current activation paths:
 
 - `session.click(id?)`
 - `session.clickAt(x, y)`
-- `dispatchKey("ENTER")` o `dispatchKey("SPACE")` cuando el foco esta en el boton
+- `dispatchKey("ENTER")` or `dispatchKey("SPACE")` when focus is on the button
 
-Payload importante:
+Important payload:
 
 - `TerminalButtonPressEventPayload` - `{ type: "press" | "click", id }`
 
 ### `List<T>`
 
-Props de `TerminalListProps<T>`:
+`TerminalListProps<T>` props:
 
 - `id?: string`
 - `focusable?: boolean`
@@ -195,14 +195,14 @@ Props de `TerminalListProps<T>`:
 - `oncapturestart?(event)`
 - `oncaptureend?(event)`
 
-Interaccion actual:
+Current interaction:
 
-- `UP` y `LEFT` mueven la seleccion hacia arriba
-- `DOWN` y `RIGHT` mueven la seleccion hacia abajo
-- `ENTER` dispara `onpress`
-- el hover por mouse expone fila, indice y valor
+- `UP` and `LEFT` move selection up
+- `DOWN` and `RIGHT` move selection down
+- `ENTER` triggers `onpress`
+- mouse hover exposes row, index, and value
 
-Payloads importantes:
+Important payloads:
 
 - `TerminalListChangeEventPayload<T>` - `{ type: "change", id, index, value }`
 - `TerminalListPressEventPayload<T>` - `{ type: "press", id, index, value }`
@@ -211,9 +211,9 @@ Payloads importantes:
 
 ### `ScrollView`
 
-Props de `TerminalScrollViewProps`:
+`TerminalScrollViewProps` props:
 
-- props de layout (`direction`, `gap`, `padding`, `border`, `width`, `height`, `id`, `focusable`)
+- layout props (`direction`, `gap`, `padding`, `border`, `width`, `height`, `id`, `focusable`)
 - `pointerCapture?: boolean`
 - `highlightRows?: number[]`
 - `onhover?(event)`
@@ -222,52 +222,52 @@ Props de `TerminalScrollViewProps`:
 - `oncapturestart?(event)`
 - `oncaptureend?(event)`
 
-Interaccion actual:
+Current interaction:
 
-- `UP` y `DOWN` ajustan el offset vertical cuando tiene foco
-- el render recorta el contenido visible segun `height`
-- `highlightRows` marca filas visibles concretas
-- el hover por mouse expone fila visible y texto renderizado
+- `UP` and `DOWN` adjust the vertical offset when it has focus
+- rendering clips visible content based on `height`
+- `highlightRows` marks specific visible rows
+- mouse hover exposes the visible row and rendered text
 
-Payloads importantes:
+Important payloads:
 
 - `TerminalScrollPointerEventPayload` - `{ type: "hover" | "rowenter" | "rowleave", id, row, value, x, y }`
 - `TerminalCaptureEventPayload` - `{ type: "capturestart" | "captureend", id, source, row, x, y }`
 
 ## `TerminalSession`
 
-Contrato publico de la sesion interactiva.
-
-- `update(): string` - vuelve a resolver la raiz y retorna la salida actual en texto plano
-- `output(): string` - devuelve el ultimo frame plano renderizado
-- `ansiOutput(): string` - devuelve el frame actual serializado con ANSI
-- `tree(): TerminalNode[]` - expone el arbol terminal resuelto actual
-- `focus(id: string): boolean` - enfoca un nodo interactivo por `id`
-- `focusAt(x: number, y: number): boolean` - enfoca por hitbox calculado
-- `focusNext(): boolean` - recorre el foco en orden de render
-- `focusPrev(): boolean` - recorre el foco hacia atras
-- `dispatchKey(key: string): string` - inyecta una tecla normalizada y devuelve la salida actual
-- `click(id?: string): string` - activa el boton enfocado o uno especifico por `id`
-- `clickAt(x: number, y: number): string` - activa o enfoca usando coordenadas
-- `clipboard(): string` - devuelve el ultimo valor de clipboard conocido por la sesion
-- `setClipboard(value: string): string` - actualiza el clipboard interno y, si existe, el adapter
-- `selectAll(): string` - selecciona todo el contenido del `Input` enfocado
-- `destroy(): void` - desmonta listeners de `stdin`, sale de raw mode y pausa el stream si aplica
-
-## Tipos utilitarios relevantes
-
-- `TerminalMountOptions` - opciones para montar la sesion
-- `TerminalClipboardAdapter` - contrato minimo para integrar clipboard externo
-- `TerminalFrame` - frame renderizado con `lines`, `hitboxes`, `cursor` y `spans`
-- `TerminalHitbox` - region interactiva calculada para foco y clicks por coordenadas
-- `TerminalStyleSpan` - marca visual como `selection`, `focus` o `highlight`
-- `TerminalNode`, `TerminalElementNode`, `TerminalTextNode` - arbol terminal resuelto
-- `TerminalLayoutProps` - base comun para `Box`, `View` y `ScrollView`
-- `TerminalFocusableProps` - `id` y `focusable`
-- `TerminalPointerCaptureProps` - `pointerCapture` para listas y scroll
-- `InputInteractionState` - posicion de cursor y ancla de seleccion
-- `TerminalChangeEventPayload` - union de cambios de `Input` y `List`
-- `TerminalPressEventPayload` - union de presses de `Button` y `List`
-- `TerminalPointerCoordinates` - coordenadas `x` y `y` opcionales en payloads de mouse
+Public contract for the interactive session.
+
+- `update(): string` - resolves the root again and returns the current plain-text output
+- `output(): string` - returns the last rendered plain frame
+- `ansiOutput(): string` - returns the current frame serialized as ANSI
+- `tree(): TerminalNode[]` - exposes the current resolved terminal tree
+- `focus(id: string): boolean` - focuses an interactive node by `id`
+- `focusAt(x: number, y: number): boolean` - focuses by computed hitbox
+- `focusNext(): boolean` - moves focus forward in render order
+- `focusPrev(): boolean` - moves focus backward in render order
+- `dispatchKey(key: string): string` - injects a normalized key and returns the current output
+- `click(id?: string): string` - activates the focused button or a specific one by `id`
+- `clickAt(x: number, y: number): string` - activates or focuses using coordinates
+- `clipboard(): string` - returns the last clipboard value known by the session
+- `setClipboard(value: string): string` - updates the internal clipboard and, if present, the adapter
+- `selectAll(): string` - selects all content in the focused `Input`
+- `destroy(): void` - removes `stdin` listeners, exits raw mode, and pauses the stream when applicable
+
+## Relevant Utility Types
+
+- `TerminalMountOptions` - options for mounting the session
+- `TerminalClipboardAdapter` - minimum contract for integrating an external clipboard
+- `TerminalFrame` - rendered frame with `lines`, `hitboxes`, `cursor`, and `spans`
+- `TerminalHitbox` - computed interactive region for focus and coordinate-based clicks
+- `TerminalStyleSpan` - visual marker such as `selection`, `focus`, or `highlight`
+- `TerminalNode`, `TerminalElementNode`, `TerminalTextNode` - resolved terminal tree
+- `TerminalLayoutProps` - shared base for `Box`, `View`, and `ScrollView`
+- `TerminalFocusableProps` - `id` and `focusable`
+- `TerminalPointerCaptureProps` - `pointerCapture` for lists and scroll views
+- `InputInteractionState` - cursor position and selection anchor
+- `TerminalChangeEventPayload` - union of `Input` and `List` change events
+- `TerminalPressEventPayload` - union of `Button` and `List` press events
+- `TerminalPointerCoordinates` - optional `x` and `y` coordinates in mouse payloads
 - `TerminalMouseEventType` - `"hover" | "rowenter" | "rowleave"`
 - `TerminalPointerSource` - `"press" | "drag" | "release"`

package/docs/cookbook.md

@@ -1,10 +1,10 @@
 # Cookbook
 
-Recetas cortas y copiables para `valyrianjs-terminal`. Esta guia complementa `docs/getting-started.md`, `docs/interaction-model.md` y `docs/api-reference.md`.
+Short, copyable recipes for `valyrianjs-terminal`. This guide complements `docs/getting-started.md`, `docs/interaction-model.md`, and `docs/api-reference.md`.
 
-## Render estatico para snapshots
+## Static rendering for snapshots
 
-Usalo cuando quieras validar layout o generar texto plano sin abrir una sesion interactiva.
+Use this when you want to validate layout or generate plain text without opening an interactive session.
 
 ```tsx
 /** @jsx v */
@@ -23,9 +23,9 @@ const output = renderTerminal(
 console.log(output);
 ```
 
-## Input controlado con submit
+## Controlled input with submit
 
-Usalo cuando necesites un campo editable que guarde el valor final al presionar `Enter`.
+Use this when you need an editable field that stores the final value when `Enter` is pressed.
 
 ```tsx
 /** @jsx v */
@@ -62,9 +62,9 @@ console.log(state.submitted);
 console.log(session.output());
 ```
 
-## Boton que muta estado
+## Button that mutates state
 
-Usalo cuando quieras activar acciones simples desde teclado o click programatico.
+Use this when you want to trigger simple actions from the keyboard or by programmatic click.
 
 ```tsx
 /** @jsx v */
@@ -95,9 +95,9 @@ session.click("increment");
 console.log(session.output());
 ```
 
-## Lista interactiva con `onchange` y `onpress`
+## Interactive list with `onchange` and `onpress`
 
-Usalo cuando quieras separar el item actualmente seleccionado del item activado con `Enter`.
+Use this when you want to separate the currently selected item from the item activated with `Enter`.
 
 ```tsx
 /** @jsx v */
@@ -134,9 +134,9 @@ console.log(state.selected);
 console.log(state.opened);
 ```
 
-## Scroll view con `height` y `highlightRows`
+## Scroll view with `height` and `highlightRows`
 
-Usalo para recortar contenido vertical y marcar filas relevantes dentro del viewport.
+Use this to clip vertical content and mark relevant rows inside the viewport.
 
 ```tsx
 /** @jsx v */
@@ -164,9 +164,9 @@ console.log(session.output());
 console.log(session.ansiOutput());
 ```
 
-## Clipboard adapter custom
+## Custom clipboard adapter
 
-Usalo cuando quieras conectar copiar y pegar con un portapapeles propio en lugar del estado interno de la sesion.
+Use this when you want to connect copy and paste to your own clipboard implementation instead of the session's internal state.
 
 ```tsx
 /** @jsx v */
@@ -212,9 +212,9 @@ console.log(session.clipboard());
 console.log(state.value);
 ```
 
-## Interaccion por coordenadas con `focusAt` y `clickAt`
+## Coordinate-based interaction with `focusAt` and `clickAt`
 
-Usalo en pruebas o adapters donde el punto de entrada real son coordenadas del frame y no ids conocidos.
+Use this in tests or adapters where the real entry point is frame coordinates rather than known ids.
 
 ```tsx
 /** @jsx v */
@@ -243,9 +243,9 @@ console.log(session.output());
 console.log(state.clicks);
 ```
 
-## Inspeccion de salida ANSI con `ansiOutput`
+## Inspect ANSI output with `ansiOutput`
 
-Usalo cuando necesites verificar cursor, estilos o secuencias ANSI en pruebas e integraciones.
+Use this when you need to verify cursor position, styles, or ANSI sequences in tests and integrations.
 
 ```tsx
 /** @jsx v */
@@ -277,10 +277,10 @@ console.log(ansi);
 console.log(/\u001b\[[0-9]+;[0-9]+H/.test(ansi));
 ```
 
-## Ver tambien
+## See also
 
-- `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
+- `docs/getting-started.md` for the minimal mounting flow
+- `docs/core-concepts.md` for the package mental model
+- `docs/interaction-model.md` for focus, keyboard, mouse, and clipboard
+- `docs/session-runtime.md` for lifecycle, streams, and session runtime
+- `docs/api-reference.md` for the full public surface