@valyrianjs/terminal 0.1.1 → 0.1.2

package/docs/cookbook.md

@@ -1,179 +1,304 @@
 # Cookbook
 
-Short, copyable recipes for `valyrianjs-terminal`. This guide complements `docs/getting-started.md`, `docs/interaction-model.md`, and `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.
 
-## Static rendering for snapshots
+## Input handling
 
-Use this when you want to validate layout or generate plain text without opening an interactive session.
+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();
 ```
 
-## Controlled input with submit
+Give the field a stable `id` if you want focus, coordinate lookup, or programmatic dispatch.
 
-Use this when you need an editable field that stores the final value when `Enter` is pressed.
+## 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();
 ```
 
-## Button that mutates state
+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.
 
-Use this when you want to trigger simple actions from the keyboard or by programmatic click.
+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();
 ```
 
-## Interactive list with `onchange` and `onpress`
+The app owns the store. The terminal session renders the current state and dispatches interaction events.
 
-Use this when you want to separate the currently selected item from the item activated with `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 with `height` and `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.
 
-Use this to clip vertical content and mark relevant rows inside the 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();
 ```
 
-## Custom clipboard adapter
+Keep log state in your app and pass entries into `LogView`.
 
-Use this when you want to connect copy and paste to your own clipboard implementation instead of the session's internal state.
+## 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();
 ```
 
-## Coordinate-based interaction with `focusAt` and `clickAt`
+Use `clipboard: false` when a session should rely on its local clipboard buffer.
 
-Use this in tests or adapters where the real entry point is frame coordinates rather than known ids.
+## 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);
-```
-
-## Inspect ANSI output with `ansiOutput`
-
-Use this when you need to verify cursor position, styles, or ANSI sequences in tests and integrations.
-
-```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));
+session.destroy();
 ```
 
 ## See also
 
-- `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
+- [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.