@valyrianjs/terminal 0.2.0 → 0.2.2

package/examples/docs/primitive-activity-console.tsx

@@ -0,0 +1,113 @@
+import {
+  Button,
+  LogView,
+  Pane,
+  Screen,
+  ScrollView,
+  Text,
+  mountTerminal
+} from "@valyrianjs/terminal";
+import type { TerminalLogViewEntry, TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface PrimitiveActivityConsoleState {
+  entries: TerminalLogViewEntry[];
+  count: number;
+  running: boolean;
+}
+
+export interface PrimitiveActivityConsoleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function addEvent(state: PrimitiveActivityConsoleState) {
+  state.count += 1;
+  state.entries = [...state.entries, { id: `event-${state.count}`, content: `event ${state.count}: operations update received` }];
+}
+
+export function App({ state }: { state: PrimitiveActivityConsoleState }) {
+  return (
+    <Screen title="Activity Console">
+      <Text>Activity Console</Text>
+      <Pane style={{ background: "#111827", padding: { x: 1, y: 0 } }}>
+        <Text>Activity timeline</Text>
+        <ScrollView id="activity-scroll" height={5}>
+          <Text>09:00 Intake queue opened</Text>
+          <Text>09:12 Billing sync completed</Text>
+          <Text>09:24 Support ticket assigned</Text>
+          <Text>09:31 Export job finished</Text>
+          <Text>09:45 Deployment window scheduled</Text>
+          <Text>10:00 Operations console ready</Text>
+        </ScrollView>
+        <LogView entries={state.entries} followTail emptyText="No events yet" />
+        <Button id="add-event" onpress={() => addEvent(state)}>Add activity event</Button>
+      </Pane>
+      <Text>Enter: add event   Up/Down: scroll when viewport has focus   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createPrimitiveActivityConsoleDemo(options: TerminalMountOptions = {}): PrimitiveActivityConsoleDemo {
+  const state: PrimitiveActivityConsoleState = { entries: [{ id: "event-0", content: "event 0: operations console ready" }], count: 0, running: true };
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    keymap: {
+      ...options.keymap,
+      bindings: [...(options.keymap?.bindings || []), { key: "CTRL_C", command: { id: "quit" }, scope: "global" }],
+      onCommand(command, context) {
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+  session.focus("add-event");
+
+  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 = createPrimitiveActivityConsoleDemo({ runtime: "headless", cols: 72, rows: 16 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createPrimitiveActivityConsoleDemo();
+  }
+}

package/examples/docs/primitive-command-panel.tsx

@@ -0,0 +1,186 @@
+import {
+  Button,
+  FocusScope,
+  Input,
+  List,
+  Overlay,
+  Screen,
+  Text,
+  mountTerminal
+} from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface PrimitiveCommandPanelState {
+  query: string;
+  selectedIndex: number;
+  picked: string;
+  running: boolean;
+}
+
+const COMMANDS = ["Open activity console", "Create ticket", "Show data explorer"] as const;
+
+export interface PrimitiveCommandPanelDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function filteredCommandsForQuery(query: string) {
+  const normalizedQuery = query.trim().toLowerCase();
+  if (!normalizedQuery) {
+    return [...COMMANDS];
+  }
+  return COMMANDS.filter((command) => command.toLowerCase().includes(normalizedQuery));
+}
+
+function clampSelectedIndex(state: PrimitiveCommandPanelState, commands: readonly string[]) {
+  if (commands.length === 0) {
+    state.selectedIndex = 0;
+    return;
+  }
+  state.selectedIndex = Math.max(0, Math.min(commands.length - 1, state.selectedIndex));
+}
+
+function pickCommand(state: PrimitiveCommandPanelState, commands = filteredCommandsForQuery(state.query)) {
+  clampSelectedIndex(state, commands);
+  state.picked = commands[state.selectedIndex] || "";
+}
+
+export function App({ state }: { state: PrimitiveCommandPanelState }) {
+  const filteredCommands = filteredCommandsForQuery(state.query);
+  clampSelectedIndex(state, filteredCommands);
+  const selectedCommand = filteredCommands[state.selectedIndex] || "none";
+
+  return (
+    <Screen title="Command Panel">
+      <Text>Command Panel</Text>
+      <Text>{state.picked ? `Picked command: ${state.picked}` : "Choose a command"}</Text>
+      <Overlay id="command-overlay" margin={{ x: "10%", y: "20%" }} trapFocus style={{ background: "#111827", padding: { x: 1, y: 0 } }}>
+        <FocusScope>
+          <Text>Command Panel</Text>
+          <Input
+            id="command-query"
+            value={state.query}
+            placeholder="Filter commands"
+            onchange={(event) => {
+              state.query = event.value;
+              clampSelectedIndex(state, filteredCommandsForQuery(state.query));
+            }}
+          />
+          <List
+            id="command-list"
+            items={filteredCommands}
+            renderItem={(item, index) => `${index === state.selectedIndex ? ">" : " "} ${item}`}
+            onchange={(event) => {
+              state.selectedIndex = event.index;
+            }}
+            onpress={() => pickCommand(state, filteredCommands)}
+          />
+          <Button id="run-command" onpress={() => pickCommand(state, filteredCommands)}>Run command</Button>
+        </FocusScope>
+      </Overlay>
+      <Text>Selected: {selectedCommand}</Text>
+      <Text>Type to filter   ↑/↓: choose   Enter: pick   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createPrimitiveCommandPanelDemo(options: TerminalMountOptions = {}): PrimitiveCommandPanelDemo {
+  const state: PrimitiveCommandPanelState = { query: "", selectedIndex: 0, picked: "", running: true };
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  function move(delta: number) {
+    const filteredCommands = filteredCommandsForQuery(state.query);
+    clampSelectedIndex(state, filteredCommands);
+    if (filteredCommands.length === 0) {
+      return;
+    }
+    const nextIndex = state.selectedIndex + delta;
+    state.selectedIndex = Math.max(0, Math.min(filteredCommands.length - 1, nextIndex));
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "input.insertText", text: "j" }, scope: "input", when: { focusedId: "command-query", focusedTag: "terminal-input" } },
+        { key: "J", command: { id: "input.insertText", text: "J" }, scope: "input", when: { focusedId: "command-query", focusedTag: "terminal-input" } },
+        { key: "k", command: { id: "input.insertText", text: "k" }, scope: "input", when: { focusedId: "command-query", focusedTag: "terminal-input" } },
+        { key: "K", command: { id: "input.insertText", text: "K" }, scope: "input", when: { focusedId: "command-query", focusedTag: "terminal-input" } },
+        { key: "j", command: { id: "command.next" }, scope: "global" },
+        { key: "J", command: { id: "command.next" }, scope: "global" },
+        { key: "DOWN", command: { id: "command.next" }, scope: "global" },
+        { key: "k", command: { id: "command.prev" }, scope: "global" },
+        { key: "K", command: { id: "command.prev" }, scope: "global" },
+        { key: "UP", command: { id: "command.prev" }, scope: "global" },
+        { key: "ENTER", command: { id: "command.pick" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "command.next") {
+          move(1);
+          return true;
+        }
+        if (command.id === "command.prev") {
+          move(-1);
+          return true;
+        }
+        if (command.id === "command.pick") {
+          pickCommand(state);
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+  session.focus("command-query");
+
+  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 = createPrimitiveCommandPanelDemo({ runtime: "headless", cols: 64, rows: 14 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createPrimitiveCommandPanelDemo();
+  }
+}

package/examples/docs/primitive-data-explorer.tsx

@@ -0,0 +1,155 @@
+import {
+  List,
+  Pane,
+  Row,
+  Screen,
+  Split,
+  Table,
+  Td,
+  Text,
+  mountTerminal
+} from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+type Item = { name: string; status: string; queue: string };
+
+interface PrimitiveDataExplorerState {
+  items: Item[];
+  selectedIndex: number;
+  running: boolean;
+}
+
+export interface PrimitiveDataExplorerDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function createInitialState(): PrimitiveDataExplorerState {
+  return {
+    selectedIndex: 0,
+    running: true,
+    items: [
+      { name: "API service", status: "healthy", queue: "8 requests" },
+      { name: "Billing queue", status: "attention", queue: "3 invoices" },
+      { name: "Reports", status: "ready", queue: "12 exports" }
+    ]
+  };
+}
+
+export function App({ state }: { state: PrimitiveDataExplorerState }) {
+  const selected = state.items[state.selectedIndex] || state.items[0];
+  return (
+    <Screen title="Service Explorer">
+      <Text>Service Explorer</Text>
+      <Split gap={1} sizes={["35%", "1fr"]}>
+        <Pane style={{ background: "#111827", padding: { x: 1, y: 0 } }}>
+          <Text>Services</Text>
+          <List
+            id="service-list"
+            items={state.items}
+            renderItem={(item, index) => `${index === state.selectedIndex ? ">" : " "} ${item.name}`}
+            onchange={(event) => {
+              state.selectedIndex = event.index;
+            }}
+          />
+        </Pane>
+        <Pane style={{ background: "#1f2937", padding: { x: 1, y: 0 } }}>
+          <Text>Details</Text>
+          <Table>
+            <Row><Td><Text>Name</Text></Td><Td><Text>{selected.name}</Text></Td></Row>
+            <Row><Td><Text>Status</Text></Td><Td><Text>{selected.status}</Text></Td></Row>
+            <Row><Td><Text>Queue</Text></Td><Td><Text>{selected.queue}</Text></Td></Row>
+          </Table>
+        </Pane>
+      </Split>
+      <Text>J/K or arrows: choose service   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createPrimitiveDataExplorerDemo(options: TerminalMountOptions = {}): PrimitiveDataExplorerDemo {
+  const state = createInitialState();
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  function move(delta: number) {
+    const nextIndex = state.selectedIndex + delta;
+    state.selectedIndex = Math.max(0, Math.min(state.items.length - 1, nextIndex));
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "service.next" }, scope: "global" },
+        { key: "J", command: { id: "service.next" }, scope: "global" },
+        { key: "DOWN", command: { id: "service.next" }, scope: "global" },
+        { key: "k", command: { id: "service.prev" }, scope: "global" },
+        { key: "K", command: { id: "service.prev" }, scope: "global" },
+        { key: "UP", command: { id: "service.prev" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "service.next") {
+          move(1);
+          return true;
+        }
+        if (command.id === "service.prev") {
+          move(-1);
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+  session.focus("service-list");
+
+  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 = createPrimitiveDataExplorerDemo({ runtime: "headless", cols: 76, rows: 14 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createPrimitiveDataExplorerDemo();
+  }
+}

package/examples/docs/primitive-input-workbench.tsx

@@ -0,0 +1,128 @@
+import {
+  Box,
+  Button,
+  Editor,
+  FocusScope,
+  Input,
+  Screen,
+  Text,
+  mountTerminal
+} from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface PrimitiveInputWorkbenchState {
+  summary: string;
+  details: string;
+  saved: string;
+  running: boolean;
+}
+
+export interface PrimitiveInputWorkbenchDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function saveTicket(state: PrimitiveInputWorkbenchState) {
+  const summary = state.summary.trim();
+  const details = state.details.trim();
+  state.saved = summary || details || "draft";
+}
+
+export function App({ state }: { state: PrimitiveInputWorkbenchState }) {
+  return (
+    <Screen title="Ticket Intake">
+      <Text>Ticket Intake</Text>
+      <FocusScope>
+        <Box direction="column" gap={1} style={{ background: "#111827", padding: { x: 1, y: 0 } }}>
+          <Text>Ticket summary</Text>
+          <Input
+            id="summary"
+            value={state.summary}
+            placeholder="Short title"
+            onchange={(event) => {
+              state.summary = event.value;
+            }}
+          />
+          <Text>Description</Text>
+          <Editor
+            id="details"
+            height={3}
+            value={state.details}
+            placeholder="Add context"
+            onchange={(event) => {
+              state.details = event.value;
+            }}
+          />
+          <Button id="save-ticket" onpress={() => saveTicket(state)}>Save ticket</Button>
+        </Box>
+      </FocusScope>
+      <Text>{state.saved ? `Saved ticket: ${state.saved}` : "Saved ticket: none"}</Text>
+      <Text>Tab: move focus   Enter: save from button   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createPrimitiveInputWorkbenchDemo(options: TerminalMountOptions = {}): PrimitiveInputWorkbenchDemo {
+  const state: PrimitiveInputWorkbenchState = { summary: "", details: "", saved: "", running: true };
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    keymap: {
+      ...options.keymap,
+      bindings: [...(options.keymap?.bindings || []), { key: "CTRL_C", command: { id: "quit" }, scope: "global" }],
+      onCommand(command, context) {
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+  session.focus("summary");
+
+  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 = createPrimitiveInputWorkbenchDemo({ runtime: "headless", cols: 64, rows: 14 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createPrimitiveInputWorkbenchDemo();
+  }
+}

package/examples/docs/primitive-layout-shell.tsx

@@ -0,0 +1,115 @@
+import {
+  Box,
+  Fixed,
+  Pane,
+  Screen,
+  Split,
+  Text,
+  View,
+  mountTerminal
+} from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface PrimitiveLayoutShellState {
+  running: boolean;
+}
+
+export interface PrimitiveLayoutShellDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+export function App({ state }: { state: PrimitiveLayoutShellState }) {
+  return (
+    <Screen title="Operations Workspace">
+      <Fixed position="top" size={2}>
+        <Text>Operations Workspace</Text>
+        <Text>Workspace status and navigation</Text>
+      </Fixed>
+      <Split gap={1} sizes={["28%", "1fr"]} breakpoints={[{ maxCols: 64, direction: "column", sizes: ["1fr", "2fr"], gap: 1 }]}>
+        <Pane style={{ background: "#111827", padding: { x: 1, y: 0 } }}>
+          <Text>Sidebar</Text>
+          <Text>Inbox</Text>
+          <Text>Reports</Text>
+          <Text>Settings</Text>
+        </Pane>
+        <Pane style={{ background: "#1f2937", padding: { x: 1, y: 0 } }}>
+          <View role="main" direction="column" gap={1}>
+            <Text>Main area</Text>
+            <Box style={{ background: "#0f172a", padding: { x: 1, y: 0 } }}>
+              <Text>Open ticket: customer export</Text>
+              <Text>Status: ready for triage</Text>
+            </Box>
+          </View>
+        </Pane>
+      </Split>
+      <Fixed position="bottom" size={1}>
+        <Text>Ctrl+C: quit</Text>
+      </Fixed>
+    </Screen>
+  );
+}
+
+export function createPrimitiveLayoutShellDemo(options: TerminalMountOptions = {}): PrimitiveLayoutShellDemo {
+  const state: PrimitiveLayoutShellState = { running: true };
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    keymap: {
+      ...options.keymap,
+      bindings: [...(options.keymap?.bindings || []), { key: "CTRL_C", command: { id: "quit" }, scope: "global" }],
+      onCommand(command, context) {
+        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 = createPrimitiveLayoutShellDemo({ runtime: "headless", cols: 72, rows: 16 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createPrimitiveLayoutShellDemo();
+  }
+}