@valyrianjs/terminal 0.2.1 → 0.2.2

package/examples/docs/employees-list.tsx

@@ -0,0 +1,138 @@
+import { Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+type Employee = {
+  name: string;
+  role: string;
+};
+
+interface EmployeesListState {
+  selectedIndex: number;
+  running: boolean;
+}
+
+export interface EmployeesListDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+const employees: Employee[] = [
+  { name: "Ana", role: "Design" },
+  { name: "Luis", role: "Support" },
+  { name: "Maya", role: "Engineering" }
+];
+
+function createInitialState(): EmployeesListState {
+  return { selectedIndex: 0, running: true };
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function EmployeeRow({ employee, selected }: { employee: Employee; selected: boolean }) {
+  return <Text>{`${selected ? ">" : " "} ${employee.name} — ${employee.role}`}</Text>;
+}
+
+function Employees({ items, selectedIndex }: { items: Employee[]; selectedIndex: number }) {
+  return (
+    <>
+      {items.map((employee, index) => (
+        <EmployeeRow employee={employee} selected={index === selectedIndex} />
+      ))}
+    </>
+  );
+}
+
+export function App({ state }: { state: EmployeesListState }) {
+  return (
+    <Screen title="Team">
+      <Employees items={employees} selectedIndex={state.selectedIndex} />
+      <Text>J/K or arrows: choose   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createEmployeesListDemo(options: TerminalMountOptions = {}): EmployeesListDemo {
+  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(employees.length - 1, nextIndex));
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "employee.next" }, scope: "global" },
+        { key: "J", command: { id: "employee.next" }, scope: "global" },
+        { key: "DOWN", command: { id: "employee.next" }, scope: "global" },
+        { key: "ARROWDOWN", command: { id: "employee.next" }, scope: "global" },
+        { key: "k", command: { id: "employee.prev" }, scope: "global" },
+        { key: "K", command: { id: "employee.prev" }, scope: "global" },
+        { key: "UP", command: { id: "employee.prev" }, scope: "global" },
+        { key: "ARROWUP", command: { id: "employee.prev" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "employee.next") {
+          move(1);
+          return true;
+        }
+        if (command.id === "employee.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 = createEmployeesListDemo({ runtime: "headless", cols: 44, rows: 8 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createEmployeesListDemo();
+  }
+}

package/examples/docs/hello.tsx

@@ -0,0 +1,98 @@
+import { Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface HelloState {
+  expanded: boolean;
+  running: boolean;
+}
+
+export interface HelloDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+function createInitialState(): HelloState {
+  return { expanded: false, running: true };
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+export function App({ state }: { state: HelloState }) {
+  return (
+    <Screen title="Hello terminal">
+      <Text>Hello from Valyrian Terminal</Text>
+      <Text>{state.expanded ? "Build terminal apps with plain components." : "Press Enter to see one detail."}</Text>
+      <Text>Enter: details   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createHelloDemo(options: TerminalMountOptions = {}): HelloDemo {
+  const state = createInitialState();
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "ENTER", command: { id: "details.toggle" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "details.toggle") {
+          state.expanded = !state.expanded;
+          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 = createHelloDemo({ runtime: "headless", cols: 42, rows: 6 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createHelloDemo();
+  }
+}

package/examples/docs/interactive-note.tsx

@@ -0,0 +1,111 @@
+import { Input, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface InteractiveNoteState {
+  value: string;
+  saved: string;
+  running: boolean;
+}
+
+export interface InteractiveNoteDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+function createInitialState(): InteractiveNoteState {
+  return { value: "", saved: "", running: true };
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+export function App({ state }: { state: InteractiveNoteState }) {
+  const draftStatus = state.value.length === 0 ? "Draft: empty" : `Draft: ${state.value.length} chars`;
+
+  return (
+    <Screen title="Notes">
+      <Text>Notes</Text>
+      <Text>{draftStatus}</Text>
+      <Input
+        id="note"
+        value={state.value}
+        placeholder="Write a note"
+        onchange={(event) => {
+          state.value = event.value;
+        }}
+        onsubmit={(event) => {
+          state.saved = event.value;
+          state.value = "";
+        }}
+      />
+      <Text>{state.saved ? `Saved: ${state.saved}` : "Last saved: none"}</Text>
+      <Text>Enter save | Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createInteractiveNoteDemo(options: TerminalMountOptions = {}): InteractiveNoteDemo {
+  const state = createInitialState();
+  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("note");
+
+  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 = createInteractiveNoteDemo({ runtime: "headless", cols: 48, rows: 8 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createInteractiveNoteDemo();
+  }
+}

package/examples/docs/module-api-dashboard.tsx

@@ -0,0 +1,307 @@
+import { QueryClient } from "valyrian.js/query";
+import { request } from "valyrian.js/request";
+import { Task } from "valyrian.js/tasks";
+import { Pane, Screen, Split, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ServiceStatus {
+  service: string;
+  queue: number;
+  version: string;
+}
+
+interface ApiDashboardState {
+  errorMode: boolean;
+  service: string;
+  queryStatus: string;
+  apiMessage: string;
+  invalidated: boolean;
+  taskStatus: string;
+  taskResult: string;
+  taskError: string;
+  taskJob: string;
+  running: boolean;
+}
+
+interface ModuleApiDashboardDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#0f172a", padding: { left: 1, right: 1 } };
+const API_STYLE = { color: "#ffffff", background: "#164e63", padding: { left: 1, right: 1 } };
+const TASK_STYLE = { color: "#ffffff", background: "#312e81", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+const ERROR_STYLE = { color: "#ffffff", background: "#7f1d1d" };
+const SUCCESS_STYLE = { color: "#ffffff", background: "#14532d" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function createState(): ApiDashboardState {
+  return {
+    errorMode: false,
+    service: "idle",
+    queryStatus: "idle",
+    apiMessage: "No request yet",
+    invalidated: false,
+    taskStatus: "idle",
+    taskResult: "Result: none",
+    taskError: "Error: none",
+    taskJob: "none",
+    running: true
+  };
+}
+
+async function withFakeFetch<T>(state: ApiDashboardState, run: () => Promise<T>) {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = ((input: RequestInfo | URL) => {
+    const url = String(input);
+    if (state.errorMode || url.endsWith("/failure")) {
+      return Promise.resolve(new Response(JSON.stringify({ message: "controlled request failure" }), { status: 503 }));
+    }
+    return Promise.resolve(new Response(JSON.stringify({ service: "healthy", queue: 3, version: "local-1" }), { status: 200 }));
+  }) as typeof fetch;
+
+  try {
+    return await run();
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+}
+
+function waitForTask(signal: AbortSignal) {
+  return new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, 20);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
+
+function syncTaskState(state: ApiDashboardState, task: Task<string, string>) {
+  const snapshot = task.state;
+  state.taskStatus = snapshot.status;
+  state.taskResult = snapshot.result ? `Result: ${snapshot.result}` : "Result: none";
+  state.taskError = snapshot.error instanceof Error ? `Error: ${snapshot.error.message}` : "Error: none";
+}
+
+export function App({ state }: { state: ApiDashboardState }) {
+  return (
+    <Screen title="API Operations Dashboard">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Valyrian.js modules in terminal apps: API dashboard</Text>
+      <Split direction="row" gap={1} sizes={["1fr", "1fr"]}>
+        <Pane style={API_STYLE}>
+          <Text>API Operations Dashboard</Text>
+          <Text>{`Mode: ${state.errorMode ? "forced error" : "success"}`}</Text>
+          <Text state={state.queryStatus === "error" ? "error" : "success"} styles={{ error: ERROR_STYLE, success: SUCCESS_STYLE }}>{state.apiMessage}</Text>
+          <Text>{`Query: ${state.queryStatus}`}</Text>
+          <Text>{`Invalidated: ${state.invalidated ? "yes" : "no"}`}</Text>
+          <Text>{`Service: ${state.service}`}</Text>
+        </Pane>
+        <Pane style={TASK_STYLE}>
+          <Text>Maintenance task</Text>
+          <Text>{`Task: ${state.taskStatus}`}</Text>
+          <Text>{`Job: ${state.taskJob}`}</Text>
+          <Text>{state.taskResult}</Text>
+          <Text>{state.taskError}</Text>
+          <Text>Request and query use a local fake fetch, so this example never calls the network.</Text>
+        </Pane>
+      </Split>
+      <Pane style={PANEL_STYLE}>
+        <Text>R: refresh   E: force error   I: invalidate   T: start task   C: cancel   Ctrl+C: quit</Text>
+        <Text style={FOOTER_STYLE}>See the Valyrian.js documentation for request, query, and tasks.</Text>
+      </Pane>
+    </Screen>
+  );
+}
+
+export function createModuleApiDashboardDemo(options: TerminalMountOptions = {}): ModuleApiDashboardDemo {
+  const state = createState();
+  const client = new QueryClient({ staleTime: 0, cacheTime: 1000 });
+  const api = request.new("http://terminal.local", { allowedMethods: ["get"] });
+  const serviceQuery = client.query({
+    key: ["terminal", "service-status"],
+    fetcher: () => api.get("/health")
+  });
+  const maintenanceTask = new Task<string, string>(async (label, { signal }) => {
+    if (label === "scan") {
+      await waitForTask(signal);
+      if (signal.aborted) return "Cancelled stale scan";
+    }
+    if (label === "fail") throw new Error("controlled task failure");
+    return `Completed ${label}`;
+  }, { strategy: "restartable" });
+  let session: TerminalSession;
+  const offTaskState = maintenanceTask.on("state", () => {
+    syncTaskState(state, maintenanceTask);
+    session?.update();
+  });
+
+  function quit() {
+    state.running = false;
+    offTaskState();
+    client.clear();
+    maintenanceTask.reset();
+    session.destroy();
+  }
+
+  async function refresh() {
+    if (state.queryStatus === "loading") {
+      state.apiMessage = "Refresh already in progress";
+      session.update();
+      return;
+    }
+
+    state.queryStatus = "loading";
+    state.apiMessage = state.errorMode ? "Loading forced error" : "Loading service status";
+    session.update();
+    try {
+      const data = (await withFakeFetch(state, () => serviceQuery.fetch())) as ServiceStatus;
+      state.service = data.service;
+      state.queryStatus = serviceQuery.state.status;
+      state.apiMessage = `Service: ${data.service}  Queue: ${data.queue}  Version: ${data.version}`;
+      state.invalidated = false;
+    } catch {
+      state.service = "unavailable";
+      state.queryStatus = serviceQuery.state.status;
+      state.apiMessage = "API error: controlled request failure";
+    }
+    session.update();
+  }
+
+  function invalidate() {
+    serviceQuery.invalidate();
+    state.queryStatus = serviceQuery.state.status;
+    state.invalidated = true;
+    state.apiMessage = "Cache invalidated; refresh will fetch again";
+    session.update();
+  }
+
+  async function runMaintenance(label: string, job: string) {
+    state.taskJob = job;
+    syncTaskState(state, maintenanceTask);
+    session.update();
+    try {
+      await maintenanceTask.run(label);
+    } catch {
+      // Task state stores the controlled error for the UI.
+    }
+    syncTaskState(state, maintenanceTask);
+    session.update();
+  }
+
+  function cancelMaintenance() {
+    state.taskJob = "stale scan";
+    void maintenanceTask.run("scan");
+    syncTaskState(state, maintenanceTask);
+    maintenanceTask.cancel();
+    syncTaskState(state, maintenanceTask);
+    session.update();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 96,
+    rows: options.rows ?? 22,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "r", command: { id: "api.refresh" }, scope: "global" },
+        { key: "R", command: { id: "api.refresh" }, scope: "global" },
+        { key: "e", command: { id: "api.error" }, scope: "global" },
+        { key: "E", command: { id: "api.error" }, scope: "global" },
+        { key: "i", command: { id: "api.invalidate" }, scope: "global" },
+        { key: "I", command: { id: "api.invalidate" }, scope: "global" },
+        { key: "t", command: { id: "task.run" }, scope: "global" },
+        { key: "T", command: { id: "task.run" }, scope: "global" },
+        { key: "c", command: { id: "task.cancel" }, scope: "global" },
+        { key: "C", command: { id: "task.cancel" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "api.refresh") {
+          void refresh();
+          return true;
+        }
+        if (command.id === "api.error") {
+          state.errorMode = true;
+          state.apiMessage = "Next refresh will use controlled error";
+          session.update();
+          return true;
+        }
+        if (command.id === "api.invalidate") {
+          invalidate();
+          return true;
+        }
+        if (command.id === "task.run") {
+          void runMaintenance("maintenance", "maintenance");
+          return true;
+        }
+        if (command.id === "task.cancel") {
+          cancelMaintenance();
+          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;
+      offTaskState();
+      client.clear();
+      maintenanceTask.reset();
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleApiDashboardDemo({ runtime: "headless", cols: 96, rows: 22 });
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("I");
+    demo.dispatchKey("E");
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("T");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("C");
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleApiDashboardDemo();
+  }
+}