@valyrianjs/terminal 0.2.1 → 0.2.2

package/docs/cookbook.md

@@ -84,7 +84,7 @@ console.log(session.output());
 session.destroy();
 ```
 
-For large lists, add `virtualized` and place the list in a bounded region such as a filled pane or split. The virtualized workbench shows the normal uncontrolled API with `itemKey`, the `children` callback, event observation, and internal active, selected, and viewport state: [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx). Run it with `bun examples/docs/virtualized-list-workbench.tsx`, move active rows with `J/K` or `Up`/`Down`, jump with `PageUp`, `PageDown`, `Home`, or `End`, select with `Enter`, and quit with `Ctrl+C`.
+For large lists, add `virtualized` and place the list in a bounded region such as a filled pane or split. The virtualized workbench demonstrates the uncontrolled List API with `itemKey`, the `children` callback, event payloads, active row, selected row, and viewport values: [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx). Shift+Up and Shift+Down are available for custom app actions. The List does not reorder items by default. Run it with `bun examples/docs/virtualized-list-workbench.tsx`, move active rows with `J/K` or `Up`/`Down`, jump with `PageUp`, `PageDown`, `Home`, or `End`, select with `Enter`, and quit with `Ctrl+C`.
 
 ## Local state to Valyrian state module bridge
 

package/docs/interaction-model.md

@@ -12,7 +12,7 @@ This guide explains how interactive primitives receive input and report events.
 
 ## Input events
 
-Keyboard dispatch uses normalized key names such as `ENTER`, `TAB`, `SHIFT_TAB`, `LEFT`, `RIGHT`, `CTRL_V`, and single-character strings. When a session is connected to `stdin`, terminal input is parsed and routed to the focused primitive.
+Keyboard dispatch uses normalized key names such as `ENTER`, `TAB`, `SHIFT_TAB`, `LEFT`, `RIGHT`, `SHIFT_UP`, `SHIFT_DOWN`, `CTRL_V`, and single-character strings. When a session is connected to `stdin`, terminal input is parsed and routed to the focused primitive.
 
 Pasted text is treated as text input for the focused primitive. Do not treat pasted strings or key sequences as terminal control instructions inside rendered content.
 
@@ -52,7 +52,7 @@ Main handlers:
 
 ### `Editor`
 
-`Editor` is a multiline editing primitive.
+`Editor` is a multiline editing primitive. Use `height` for a bounded multiline viewport, `width` for a fixed frame width, and `fill` when the editor should behave like a textarea surface that consumes available width and height. Explicit dimensions win over `fill`; without those props, existing content-sized rendering stays intact.
 
 Supported behavior includes:
 
@@ -93,13 +93,13 @@ A quick second primary mouse press keeps the normal activation behavior and also
 
 ### `List`
 
-`List` models active row movement, optional visible selection, viewport scroll, and activation. In virtualized mode the component receives the full `items` array and owns the viewport; wheel input moves the viewport, while keyboard list commands move the active row and emit `change`. A JSX `children` callback receives `(item, ctx)` with `ctx.active`, `ctx.selected`, `ctx.index`, `ctx.key`, and `ctx.viewportIndex`; it takes precedence over `renderItem`. Use `itemKey` when rows have stable identities across reorder or filtering.
+`List` models active row movement, optional visible selection, viewport scroll, and activation. In virtualized mode, pass the full `items` array; the list shows the visible viewport, wheel input scrolls it, and keyboard list commands move the active row and emit `change`. A JSX `children` callback receives `(item, ctx)` with `ctx.active`, `ctx.selected`, `ctx.index`, `ctx.key`, and `ctx.viewportIndex`; it takes precedence over `renderItem`. Use `itemKey` when rows have stable identities across reorder or filtering.
 
 Supported behavior includes:
 
 - `UP` and `DOWN` move the active row and emit `onchange`
 - `PageUp`, `PageDown`, `Home`, and `End` jump the active row and keep it visible
-- `LEFT` and `RIGHT` have no default list command, so applications can bind them
+- `LEFT`, `RIGHT`, `SHIFT_UP`, and `SHIFT_DOWN` have no default list command, so applications can bind them
 - `ENTER` selects and activates the active row
 - mouse click selects and activates the target row
 - mouse hover reports row details when mouse input is connected
@@ -118,7 +118,7 @@ Main handlers:
 - `oncapturestart`
 - `oncaptureend`
 
-`pointerCapture` lets a list keep drag interaction even when the pointer leaves the initial hitbox.
+`pointerCapture` lets a list keep drag interaction even when the pointer leaves the initial hitbox. If your app needs reordering, priority changes, or other modified-arrow behavior, bind `SHIFT_UP` or `SHIFT_DOWN` through `keymap.bindings` and handle the custom command in `keymap.onCommand`. The list will not mutate item order by default.
 
 ### `ScrollView`
 

package/docs/primitive-gallery.md

@@ -176,12 +176,12 @@ Use `Editor` for notes, descriptions, and longer messages.
 
 **What it is:** A multi-line editable field.
 **Use it for:** notes, descriptions, and longer messages.
-**Core props:** `id`, `value`, `placeholder`, `height`, `onchange`, `oninput`, `onsubmit`, `oncancel`.
+**Core props:** `id`, `value`, `placeholder`, `width`, `height`, `fill`, `onchange`, `oninput`, `onsubmit`, `oncancel`.
 
 **Minimal example:**
 
 ```tsx
-<Editor id="details" height={4} value={details} onchange={(event) => { details = event.value; }} />
+<Editor id="details" fill height={4} value={details} onchange={(event) => { details = event.value; }} />
 ```
 
 **Complete demo:** [`examples/docs/primitive-input-workbench.tsx`](../examples/docs/primitive-input-workbench.tsx). Run it with `bun examples/docs/primitive-input-workbench.tsx` and quit with `Ctrl+C`.
@@ -228,7 +228,7 @@ Use `List` for menus, choosers, command lists, and item browsers.
 
 **What it is:** A focusable collection control with selection and press events.
 **Use it for:** menus, choosers, command lists, and item browsers.
-**Core props:** `id`, `items`, `children` callback, `renderItem`, `itemKey`, `virtualized`, `showActive`, `onchange`, `onviewportchange`, `onpress`, `ondoublepress`, `oncontextpress`. `List` owns its active row, selected row, and viewport state internally; observe those values from event payloads.
+**Core props:** `id`, `items`, `children` callback, `renderItem`, `itemKey`, `virtualized`, `showActive`, `onchange`, `onviewportchange`, `onpress`, `ondoublepress`, `oncontextpress`. `List` manages its active row, selected row, and viewport state. Read those values from event payloads.
 
 **Minimal example:**
 
@@ -240,7 +240,7 @@ Use `List` for menus, choosers, command lists, and item browsers.
 
 **Complete demo:** [`examples/docs/primitive-data-explorer.tsx`](../examples/docs/primitive-data-explorer.tsx). Run it with `bun examples/docs/primitive-data-explorer.tsx` and quit with `Ctrl+C`.
 
-**Virtualized demo:** [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx). Run it with `bun examples/docs/virtualized-list-workbench.tsx`, move active rows with `J/K` or `Up`/`Down`, jump with `PageUp`, `PageDown`, `Home`, or `End`, select with `Enter`, and quit with `Ctrl+C`.
+**Virtualized demo:** [`examples/docs/virtualized-list-workbench.tsx`](../examples/docs/virtualized-list-workbench.tsx). Run it with `bun examples/docs/virtualized-list-workbench.tsx`, move active rows with `J/K` or `Up`/`Down`, jump with `PageUp`, `PageDown`, `Home`, or `End`, select with `Enter`, and quit with `Ctrl+C`. `Shift+Up` and `Shift+Down` are shown as app-defined commands, not built-in reorder behavior.
 
 ### `Table`
 

package/examples/basic.tsx

@@ -0,0 +1,22 @@
+import { mountTerminal } from "../dist/index.js";
+import { createDemoState, DemoApp, renderDemoSnapshot } from "./demo.js";
+
+const state = createDemoState();
+
+if (process.argv.includes("--snapshot")) {
+  console.log(renderDemoSnapshot(state));
+} else {
+  const session = mountTerminal(() => <DemoApp state={state} />, {
+    stdin: process.stdin,
+    stdout: process.stdout
+  });
+
+  session.focus("name");
+
+  const shutdown = () => {
+    session.destroy();
+    process.exit(0);
+  };
+
+  process.on("SIGINT", shutdown);
+}

package/examples/cli.tsx

@@ -0,0 +1,55 @@
+#!/usr/bin/env bun
+import { mountTerminal } from "../dist/index.js";
+import { createDemoState, DemoApp, renderDemoSnapshot } from "./demo.js";
+
+export function shouldExitCliChunk(chunk: string | Uint8Array) {
+  const value = typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8");
+  if (value.length !== 1) {
+    return false;
+  }
+  const code = value.charCodeAt(0);
+  return code === 27 || code === 3;
+}
+
+function printHelp() {
+  console.log("valyrianjs-terminal local demo");
+  console.log("");
+  console.log("Usage:");
+  console.log("  bun run examples/cli.tsx [--snapshot]");
+  console.log("  bun run examples/cli.tsx --help");
+}
+
+const args = new Set(process.argv.slice(2));
+
+if (args.has("--help") || args.has("-h")) {
+  printHelp();
+  process.exit(0);
+}
+
+const state = createDemoState();
+
+if (args.has("--snapshot")) {
+  console.log(renderDemoSnapshot(state));
+} else {
+  const session = mountTerminal(() => <DemoApp state={state} />, {
+    stdin: process.stdin,
+    stdout: process.stdout
+  });
+
+  session.focus("menu");
+
+  const shutdown = () => {
+    process.stdin.off?.("data", onGlobalData);
+    session.destroy();
+    process.exit(0);
+  };
+
+  const onGlobalData = (chunk: string | Uint8Array) => {
+    if (shouldExitCliChunk(chunk)) {
+      shutdown();
+    }
+  };
+
+  process.stdin.on("data", onGlobalData);
+  process.on("SIGINT", shutdown);
+}

package/examples/demo.tsx

@@ -0,0 +1,98 @@
+import type {
+  TerminalInputChangeEventPayload,
+  TerminalInputSubmitEventPayload,
+  TerminalListChangeEventPayload,
+  TerminalListPressEventPayload
+} from "../dist/index.js";
+import { Button, Fixed, Input, List, mountTerminal, Pane, Row, Screen, ScrollView, Split, Table, Td, Text } from "../dist/index.js";
+
+export function createDemoState() {
+  return {
+    name: "",
+    selected: "Inbox",
+    saved: "",
+    items: ["Inbox", "Today", "Done"],
+    shortcuts: [
+      ["Tab", "Move focus"],
+      ["Arrows", "Browse queue"],
+      ["Enter", "Activate/save"],
+      ["Esc", "Quit demo"]
+    ]
+  };
+}
+
+export function DemoApp(props: { state: ReturnType<typeof createDemoState> }) {
+  const { state } = props;
+
+  return (
+    <Screen>
+      <Fixed position="top" size={4}>
+        <Pane fill style="pane.header" padding={1}>
+          <Text>Valyrian Terminal Demo</Text>
+          <Text>Queue workbench for triage and quick entry</Text>
+        </Pane>
+      </Fixed>
+
+      <Split fill direction="row" gap={1}>
+        <Pane fill style="pane.transcript" padding={1}>
+          <Text>Queues</Text>
+          <Text>Arrow keys to browse</Text>
+          <List
+            id="menu"
+            items={state.items}
+            onchange={(event: TerminalListChangeEventPayload<string>) => (state.selected = event.value)}
+            onpress={(event: TerminalListPressEventPayload<string>) => (state.saved = `Opened:${event.value}`)}
+          />
+        </Pane>
+
+        <Pane fill style="pane.tools" padding={1}>
+          <Text>Quick Entry</Text>
+          <Text>{`Draft for ${state.selected}`}</Text>
+          <Input
+            id="name"
+            value={state.name}
+            placeholder="Write a quick note"
+            onchange={(event: TerminalInputChangeEventPayload) => (state.name = event.value)}
+            onsubmit={(event: TerminalInputSubmitEventPayload) => (state.saved = `Submitted:${event.value || state.selected}`)}
+          />
+          <Button id="save" onpress={() => (state.saved = `Saved:${state.name || state.selected}`)}>Save Current</Button>
+
+          <Text>Activity</Text>
+          <ScrollView id="details" height={4}>
+            <Text>{`Selected : ${state.selected}`}</Text>
+            <Text>{`Draft    : ${state.name || "-"}`}</Text>
+            <Text>{`Saved    : ${state.saved || "-"}`}</Text>
+            <Text>Tip      : Press Tab to switch panels</Text>
+            <Text>Tip      : Enter saves current value</Text>
+          </ScrollView>
+
+          <Text>Shortcuts</Text>
+          <Table v-for={state.shortcuts}>
+            {(row: string[]) => (
+              <Row>
+                <Td>{row[0]}</Td>
+                <Td>{row[1]}</Td>
+              </Row>
+            )}
+          </Table>
+        </Pane>
+      </Split>
+
+      <Fixed position="bottom" size={3}>
+        <Pane fill style="pane.prompt" padding={1}>
+          <Text>Tab move focus | Enter activate | Ctrl+C quit</Text>
+        </Pane>
+      </Fixed>
+    </Screen>
+  );
+}
+
+export function renderDemoSnapshot(state = createDemoState()) {
+  const session = mountTerminal(<DemoApp state={state} />, { cols: 80, rows: 24, clipboard: false });
+
+  try {
+    return session.output();
+  } finally {
+    session.destroy();
+  }
+}

package/examples/docs/background-fill.tsx

@@ -0,0 +1,107 @@
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface BackgroundFillState {
+  surface: "panel" | "card";
+  running: boolean;
+}
+
+export interface BackgroundFillDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+const theme = { styles: { pane: { main: { background: "#111111" }, card: { background: "#1f2937" } } } };
+
+function createInitialState(): BackgroundFillState {
+  return { surface: "panel", running: true };
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+export function App({ state }: { state: BackgroundFillState }) {
+  const isCard = state.surface === "card";
+
+  return (
+    <Screen title="Filled panel">
+      <Text>{isCard ? "Surface: card background" : "Surface: panel background"}</Text>
+      <Text>Look for the filled 34-column panel behind the content.</Text>
+      <Pane fill width={34} height={5} style={isCard ? "pane.card" : "pane.main"}>
+        <Text>{isCard ? "Card content" : "Panel content"}</Text>
+      </Pane>
+      <Text>B: switch surface   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createBackgroundFillDemo(options: TerminalMountOptions = {}): BackgroundFillDemo {
+  const state = createInitialState();
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    theme,
+    ...options,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "b", command: { id: "surface.switch" }, scope: "global" },
+        { key: "B", command: { id: "surface.switch" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "surface.switch") {
+          state.surface = state.surface === "panel" ? "card" : "panel";
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createBackgroundFillDemo({ runtime: "headless", cols: 42, rows: 9 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createBackgroundFillDemo();
+  }
+}

package/examples/docs/component-composition.tsx

@@ -0,0 +1,140 @@
+import { Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface Profile {
+  name: string;
+  role: string;
+  status: string;
+}
+
+interface ComponentCompositionState {
+  selectedIndex: number;
+  running: boolean;
+}
+
+export interface ComponentCompositionDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+const profiles: Profile[] = [
+  { name: "Maya", role: "Engineering", status: "Ready" },
+  { name: "Ana", role: "Design", status: "Reviewing" },
+  { name: "Luis", role: "Support", status: "Helping customers" }
+];
+
+function createInitialState(): ComponentCompositionState {
+  return { selectedIndex: 0, running: true };
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function StatusBadge({ status }: { status: string }) {
+  return <Text>Status: {status}</Text>;
+}
+
+function Greeting({ name }: { name: string }) {
+  return <Text>Hello, {name}</Text>;
+}
+
+function ProfileCard({ profile }: { profile: Profile }) {
+  return (
+    <>
+      <Greeting name={profile.name} />
+      <Text>Role: {profile.role}</Text>
+      <StatusBadge status={profile.status} />
+    </>
+  );
+}
+
+export function App({ state }: { state: ComponentCompositionState }) {
+  return (
+    <Screen title="Components">
+      <ProfileCard profile={profiles[state.selectedIndex]} />
+      <Text>N/P: switch card   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createComponentCompositionDemo(options: TerminalMountOptions = {}): ComponentCompositionDemo {
+  const state = createInitialState();
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  function move(delta: number) {
+    state.selectedIndex = (state.selectedIndex + delta + profiles.length) % profiles.length;
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "n", command: { id: "card.next" }, scope: "global" },
+        { key: "N", command: { id: "card.next" }, scope: "global" },
+        { key: "RIGHT", command: { id: "card.next" }, scope: "global" },
+        { key: "p", command: { id: "card.prev" }, scope: "global" },
+        { key: "P", command: { id: "card.prev" }, scope: "global" },
+        { key: "LEFT", command: { id: "card.prev" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "card.next") {
+          move(1);
+          return true;
+        }
+        if (command.id === "card.prev") {
+          move(-1);
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createComponentCompositionDemo({ runtime: "headless", cols: 44, rows: 8 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createComponentCompositionDemo();
+  }
+}

package/examples/docs/cursor.tsx

@@ -0,0 +1,121 @@
+import { Input, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface CursorState {
+  value: string;
+  cursorNote: string;
+  running: boolean;
+}
+
+export interface CursorDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+function createInitialState(): CursorState {
+  return {
+    value: "ready",
+    cursorNote: "Terminal cursor hidden while this app owns the screen",
+    running: true
+  };
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+export function App({ state }: { state: CursorState }) {
+  return (
+    <Screen title="Cursor demo">
+      <Text>Cursor demo</Text>
+      <Text>App hides the terminal cursor while it owns the screen.</Text>
+      <Text>Focused input keeps its editing cursor visible.</Text>
+      <Input
+        id="search"
+        value={state.value}
+        placeholder="Type here"
+        onchange={(event) => {
+          state.value = event.value;
+        }}
+      />
+      <Text>{`Input value: ${state.value}`}</Text>
+      <Text>{state.cursorNote}</Text>
+      <Text>Type: edit field | C: cursor note | Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createCursorDemo(options: TerminalMountOptions = {}): CursorDemo {
+  const state = createInitialState();
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    hideCursor: true,
+    restoreOnDestroy: true,
+    ...options,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "c", command: { id: "cursor.note" }, scope: "global" },
+        { key: "C", command: { id: "cursor.note" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "cursor.note") {
+          state.cursorNote = state.cursorNote.startsWith("Terminal cursor hidden")
+            ? "Terminal restores the cursor when the app closes"
+            : "Terminal cursor hidden while this app owns the screen";
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  session.focus("search");
+
+  return {
+    session,
+    dispatchKey(key: string) {
+      return session.dispatchKey(key);
+    },
+    output() {
+      return session.output();
+    },
+    ansiOutput() {
+      return session.ansiOutput();
+    },
+    isRunning() {
+      return state.running;
+    },
+    destroy() {
+      state.running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createCursorDemo({ runtime: "headless", cols: 56, rows: 7 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createCursorDemo();
+  }
+}