@valyrianjs/terminal 0.1.0 → 0.1.2

package/docs/cookbook.md

@@ -1,179 +1,304 @@
 # Cookbook
 
-Recetas cortas y copiables para `valyrianjs-terminal`. Esta guia complementa `docs/getting-started.md`, `docs/interaction-model.md` y `docs/api-reference.md`.
+Practical recipes for ValyrianJS Terminal. Start here after [Getting Started](./getting-started.md) when you want copyable patterns for common terminal UI tasks.
 
-## Render estatico para snapshots
+## Input handling
 
-Usalo cuando quieras validar layout o generar texto plano sin abrir una sesion interactiva.
+Use `Input` when a single-line field should update app state and optionally submit on `Enter`.
+
+Full example: [`examples/docs/interactive-note.tsx`](../examples/docs/interactive-note.tsx). Run it with `bun examples/docs/interactive-note.tsx`, type a note, press `Enter`, and quit with `Ctrl+C`.
 
 ```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
+import { Input, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
 
-import { v } from "valyrian.js";
-import { Screen, Text, renderTerminal } from "valyrianjs-terminal";
+const state = { value: "", submitted: "" };
 
-const output = renderTerminal(
-  <Screen title="Snapshot Demo">
-    <Text>Hello terminal</Text>
-    <Text>Status: ok</Text>
-  </Screen>
-);
+function App() {
+  return (
+    <Screen title="Input recipe">
+      <Input
+        id="name"
+        value={state.value}
+        placeholder="Name"
+        onchange={(event) => {
+          state.value = event.value;
+        }}
+        onsubmit={(event) => {
+          state.submitted = event.value;
+        }}
+      />
+      <Text>{state.submitted || "Nothing submitted yet"}</Text>
+    </Screen>
+  );
+}
+
+const session = mountTerminal(<App />);
 
-console.log(output);
+session.focus("name");
+session.dispatchKey("A");
+session.dispatchKey("ENTER");
+
+console.log(session.output());
+session.destroy();
 ```
 
-## Input controlado con submit
+Give the field a stable `id` if you want focus, coordinate lookup, or programmatic dispatch.
 
-Usalo cuando necesites un campo editable que guarde el valor final al presionar `Enter`.
+## Lists and selection
 
-```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
+Use `List` when the app needs selection and activation as separate events.
 
-import { v } from "valyrian.js";
-import { Input, Screen, Text, mountTerminal } from "valyrianjs-terminal";
+Related example: [`examples/docs/employees-list.tsx`](../examples/docs/employees-list.tsx). Run it with `bun examples/docs/employees-list.tsx`, choose a person with `J/K` or arrows, and quit with `Ctrl+C`.
 
-const state = { value: "", submitted: "" };
+```tsx
+import { List, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+
+const state = { selected: "", opened: "" };
 
-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>
-));
+function App() {
+  return (
+    <Screen title="List recipe">
+      <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>
+  );
+}
+
+const session = mountTerminal(<App />);
 
-session.focus("name");
-session.dispatchKey("H");
-session.dispatchKey("i");
+session.focus("menu");
+session.dispatchKey("DOWN");
 session.dispatchKey("ENTER");
 
-console.log(state.submitted);
 console.log(session.output());
+session.destroy();
 ```
 
-## Boton que muta estado
+For large lists, add `virtualized` and place the list in a bounded region such as a filled pane or split.
+
+## Local state to Valyrian state module bridge
+
+Start with local objects for small examples. Use Valyrian state modules such as `createPulseStore` when shared state and named transitions make the UI easier to maintain.
 
-Usalo cuando quieras activar acciones simples desde teclado o click programatico.
+Related example: [`examples/docs/component-composition.tsx`](../examples/docs/component-composition.tsx). Run it with `bun examples/docs/component-composition.tsx`, switch cards with `N/P`, and quit with `Ctrl+C`.
 
 ```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");
+import { createPulseStore } from "valyrian.js/pulses";
+import { Button, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+
+const counter = createPulseStore(
+  { count: 0 },
+  {
+    increment(state) {
+      state.count += 1;
+    }
+  }
+);
+
+function App() {
+  return (
+    <Screen title="State recipe">
+      <Text>Count: {counter.state.count}</Text>
+      <Button id="increment" onpress={() => counter.increment()}>
+        Increment
+      </Button>
+    </Screen>
+  );
+}
+
+const session = mountTerminal(<App />);
+
+session.focus("increment");
+session.dispatchKey("ENTER");
 
 console.log(session.output());
+session.destroy();
 ```
 
-## Lista interactiva con `onchange` y `onpress`
+The app owns the store. The terminal session renders the current state and dispatches interaction events.
 
-Usalo cuando quieras separar el item actualmente seleccionado del item activado con `Enter`.
 
-```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
+## Primitive Gallery mini apps
 
-import { v } from "valyrian.js";
-import { List, Screen, Text, mountTerminal } from "valyrianjs-terminal";
+Use [Primitive Gallery](./primitive-gallery.md) when you want to pick the right primitive before copying a recipe. The gallery shows what each primitive is, where it fits, core props, a short example, and a complete mini app.
 
-const state = { selected: "", opened: "" };
+Complete primitive demos:
 
-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>
-));
+- **Operations Workspace** ([`examples/docs/primitive-layout-shell.tsx`](../examples/docs/primitive-layout-shell.tsx)). Run it with `bun examples/docs/primitive-layout-shell.tsx`, inspect the shell regions, and quit with `Ctrl+C`.
+- **Ticket Intake** ([`examples/docs/primitive-input-workbench.tsx`](../examples/docs/primitive-input-workbench.tsx)). Run it with `bun examples/docs/primitive-input-workbench.tsx`, type a summary, move focus with `Tab`, save with `Enter`, and quit with `Ctrl+C`.
+- **Service Explorer** ([`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx)). Run it with `bun examples/docs/primitive-data-explorer.tsx`, move through items with `J/K`, and quit with `Ctrl+C`.
+- **Activity Console** ([`examples/docs/primitive-activity-console.tsx`](../examples/docs/primitive-activity-console.tsx)). Run it with `bun examples/docs/primitive-activity-console.tsx`, add events with `Enter`, scroll the viewport with `Up/Down`, and quit with `Ctrl+C`.
+- **Command Panel** ([`examples/docs/primitive-command-panel.tsx`](../examples/docs/primitive-command-panel.tsx)). Run it with `bun examples/docs/primitive-command-panel.tsx`, type a filter, choose commands with arrows, pick with `Enter`, and quit with `Ctrl+C`.
 
-session.focus("menu");
-session.dispatchKey("DOWN");
-session.dispatchKey("DOWN");
+Use API Reference for prop-level details after you choose the primitive family.
+
+## Valyrian.js modules in terminal apps
+
+Valyrian.js modules let terminal apps use the same app-layer tools you would use in Valyrian browser or server apps. The terminal adapter owns rendering, focus, input dispatch, output, and cleanup. Your app owns state, data, persistence, commands, and business rules.
+
+Read the dedicated guide at [`docs/valyrian-modules.md`](./valyrian-modules.md) for deeper patterns around `valyrian.js/request`, `valyrian.js/query`, `valyrian.js/tasks`, state modules, forms, persistence, localization, money formatting, and utilities.
+
+Complete terminal demos:
+
+- **Operations Workbench** ([`examples/docs/module-state-workbench.tsx`](../examples/docs/module-state-workbench.tsx)). Run it with `bun examples/docs/module-state-workbench.tsx`, select jobs with `J/K`, dispatch with `Enter`, mark work with `D` or `B`, reset with `R`, and quit with `Ctrl+C`.
+- **API Operations Dashboard** ([`examples/docs/module-api-dashboard.tsx`](../examples/docs/module-api-dashboard.tsx)). Run it with `bun examples/docs/module-api-dashboard.tsx`, refresh with `R`, toggle a controlled error with `E`, invalidate with `I`, run or cancel the task with `T` or `C`, and quit with `Ctrl+C`.
+- **Billing/Settings Wizard** ([`examples/docs/module-form-workflow.tsx`](../examples/docs/module-form-workflow.tsx)). Run it with `bun examples/docs/module-form-workflow.tsx`, fill values with `N`, switch language with `L`, save with `S` or `Enter`, reset with `R`, clear saved data with `X`, and quit with `Ctrl+C`.
+
+## Overlay or modal-like composition
+
+Use `Overlay` and `FocusScope` for app-local popovers or lightweight dialog surfaces. The app owns whether the surface is present and what action is performed.
+
+Related example: [`examples/docs/component-composition.tsx`](../examples/docs/component-composition.tsx). Run it with `bun examples/docs/component-composition.tsx`, switch cards with `N/P`, and quit with `Ctrl+C`.
+
+```tsx
+import { FocusScope, Input, List, Overlay, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+
+const commands = ["Open file", "Run task", "Toggle panel"];
+const state = { query: "", executed: "" };
+
+function App() {
+  const visible = commands.filter((command) =>
+    command.toLowerCase().includes(state.query.toLowerCase())
+  );
+
+  return (
+    <Screen title="Overlay recipe">
+      <Text>{state.executed ? `Executed: ${state.executed}` : "Choose a command"}</Text>
+      <Overlay x={2} y={2} width={40} height={6} trapFocus>
+        <FocusScope>
+          <Input
+            id="query"
+            value={state.query}
+            placeholder="Search"
+            onchange={(event) => {
+              state.query = event.value;
+            }}
+          />
+          <List
+            id="results"
+            items={visible}
+            onpress={(event) => {
+              state.executed = event.value;
+            }}
+          />
+        </FocusScope>
+      </Overlay>
+    </Screen>
+  );
+}
+
+const session = mountTerminal(<App />);
+
+session.focus("query");
+session.dispatchKey("R");
+session.focus("results");
 session.dispatchKey("ENTER");
 
-console.log(state.selected);
-console.log(state.opened);
+console.log(session.output());
+session.destroy();
 ```
 
-## Scroll view con `height` y `highlightRows`
+This local composition uses public focus, overlay, input, and list primitives. Keep shared command catalogs, permissions, and workflow orchestration in the app layer when the palette grows.
 
-Usalo para recortar contenido vertical y marcar filas relevantes dentro del viewport.
+## Log view / follow-tail behavior with `LogView`
+
+Use `LogView` for append-only logs or transcript-like panes. `followTail` is a `LogView` option, not a standalone primitive.
+
+Related example: [`examples/docs/component-composition.tsx`](../examples/docs/component-composition.tsx). Run it with `bun examples/docs/component-composition.tsx`, switch cards with `N/P`, and quit with `Ctrl+C`.
 
 ```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());
+import { LogView, Screen, mountTerminal } from "@valyrianjs/terminal";
+
+const entries = [
+  { id: "1", content: "User: hello" },
+  { id: "2", content: "System: ready" },
+  { id: "3", content: "User: summarize the latest output" }
+];
+
+function App() {
+  return (
+    <Screen title="Log recipe">
+      <LogView
+        height={3}
+        entries={entries}
+        followTail
+        emptyText="No entries yet"
+        renderEntry={(entry) => entry.content}
+      />
+    </Screen>
+  );
+}
+
+const session = mountTerminal(<App />, { cols: 80, rows: 8 });
 
-session.dispatchKey("DOWN");
 console.log(session.output());
-console.log(session.ansiOutput());
+session.destroy();
 ```
 
-## Clipboard adapter custom
+Keep log state in your app and pass entries into `LogView`.
 
-Usalo cuando quieras conectar copiar y pegar con un portapapeles propio en lugar del estado interno de la sesion.
+## Full-terminal layout
+
+Use `Screen`, `Fixed`, `Split`, and `Pane` when a session should fill the available terminal size. `Split` uses the available body area from context, and panes take available width by default. Use `fill` when a surface should consume the full available height; block containers otherwise stack at content height.
+
+Full example: [`examples/docs/background-fill.tsx`](../examples/docs/background-fill.tsx). Run it with `bun examples/docs/background-fill.tsx`, switch surfaces with `B`, and quit with `Ctrl+C`.
 
 ```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
+import { Fixed, Pane, Screen, Split, Text, mountTerminal } from "@valyrianjs/terminal";
+
+function App() {
+  return (
+    <Screen title="Workspace">
+      <Fixed position="top" size={3}>
+        <Pane fill style={{ background: "#111111", padding: 1 }}>
+          <Text>Header</Text>
+        </Pane>
+      </Fixed>
+      <Split direction="row" gap={1}>
+        <Pane fill style={{ background: "#111111", padding: 1 }}>
+          <Text>Main content</Text>
+        </Pane>
+        <Pane fill style={{ background: "#111111", padding: 1 }}>
+          <Text>Side panel</Text>
+        </Pane>
+      </Split>
+      <Fixed position="bottom" size={3}>
+        <Pane fill style={{ background: "#111111", padding: 1 }}>
+          <Text>Ready</Text>
+        </Pane>
+      </Fixed>
+    </Screen>
+  );
+}
+
+const session = mountTerminal(<App />, { cols: 80, rows: 24 });
+
+console.log(session.output());
+session.destroy();
+```
+
+Styles are expressed as recipes or inline style objects. The renderer translates those styles to supported terminal output for the current session, so avoid depending on raw ANSI sequences in rendered content. For style recipes in a runnable ANSI app, run `bun examples/docs/style-system.tsx`, use `Tab`, `Enter`, and `W` to change state, and quit with `Ctrl+C`; or open [`examples/docs/style-system.tsx`](../examples/docs/style-system.tsx). For responsive split sizing, run `bun examples/docs/responsive-split.tsx`, resize the terminal to change the layout, and quit with `Ctrl+C`; or open [`examples/docs/responsive-split.tsx`](../examples/docs/responsive-split.tsx).
+
+For a full-screen responsive pizza builder with ingredient selection, `Split` fractions, a running total, and simulated checkout, run `bun examples/docs/pizza-builder.tsx`, choose toppings with `Up/Down` and `Space`, press `Enter`, resize with `R`, clear with `C`, and quit with `Ctrl+C`; or open [`examples/docs/pizza-builder.tsx`](../examples/docs/pizza-builder.tsx).
+
+## Clipboard adapter
 
-import { v } from "valyrian.js";
-import { Input, Screen, mountTerminal } from "valyrianjs-terminal";
+Use a clipboard adapter when copy and paste should go through an application-provided clipboard implementation.
+
+Related example: [`examples/docs/interactive-note.tsx`](../examples/docs/interactive-note.tsx). Run it with `bun examples/docs/interactive-note.tsx`, type a note, press `Enter`, and quit with `Ctrl+C`.
+
+```tsx
+import { Input, Screen, mountTerminal } from "@valyrianjs/terminal";
 
 const state = { value: "abcd" };
 const clipboard = {
@@ -186,101 +311,71 @@ const clipboard = {
   }
 };
 
-const session = mountTerminal(() => (
-  <Screen>
-    <Input
-      id="name"
-      value={state.value}
-      onchange={(event) => {
-        state.value = event.value;
-      }}
-    />
-  </Screen>
-), { clipboard });
+function App() {
+  return (
+    <Screen title="Clipboard recipe">
+      <Input
+        id="name"
+        value={state.value}
+        onchange={(event) => {
+          state.value = event.value;
+        }}
+      />
+    </Screen>
+  );
+}
+
+const session = mountTerminal(<App />, { clipboard });
 
 session.focus("name");
-session.dispatchKey("HOME");
-session.dispatchKey("SHIFT_RIGHT");
-session.dispatchKey("SHIFT_RIGHT");
+session.dispatchKey("CTRL_A");
 session.dispatchKey("CTRL_C");
 
-clipboard.value = "XY";
-session.dispatchKey("END");
-session.dispatchKey("CTRL_V");
-
 console.log(session.clipboard());
-console.log(state.value);
+session.destroy();
 ```
 
-## Interaccion por coordenadas con `focusAt` y `clickAt`
+Use `clipboard: false` when a session should rely on its local clipboard buffer.
 
-Usalo en pruebas o adapters donde el punto de entrada real son coordenadas del frame y no ids conocidos.
+## Coordinate-based interaction
 
-```tsx
-/** @jsx v */
-/** @jsxFrag v.fragment */
+Use `focusAt` and `clickAt` when an adapter receives frame coordinates instead of known ids.
+
+Related example: [`examples/docs/cursor.tsx`](../examples/docs/cursor.tsx). Run it with `bun examples/docs/cursor.tsx`, type text, press `C`, and quit with `Ctrl+C`.
 
-import { v } from "valyrian.js";
-import { Button, Input, Screen, mountTerminal } from "valyrianjs-terminal";
+```tsx
+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>
-));
+function App() {
+  return (
+    <Screen title="Coordinates">
+      <Input id="name" value="abc" />
+      <Button id="save" onpress={() => {
+        state.clicks += 1;
+      }}>
+        Save
+      </Button>
+    </Screen>
+  );
+}
+
+const session = mountTerminal(<App />);
 
 session.focusAt(2, 1);
 session.clickAt(3, 2);
 
 console.log(session.output());
 console.log(state.clicks);
+session.destroy();
 ```
 
-## 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
+## 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
+- [Getting Started](./getting-started.md) for the first project.
+- [Core Concepts](./core-concepts.md) for the mental model.
+- [Interaction Model](./interaction-model.md) for focus, keyboard, mouse, and event behavior.
+- [Valyrian Modules](./valyrian-modules.md)
+- [Session Runtime](./session-runtime.md) for streams and host integration.
+- [API Reference](./api-reference.md) for props, payloads, and session methods.