@valyrianjs/terminal 0.2.1 → 0.2.2

package/examples/docs/module-pulses.tsx

@@ -0,0 +1,142 @@
+import { createPulse } from "valyrian.js/pulses";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+type ShiftPulses = {
+  open: () => number;
+  resolved: () => number;
+  priority: () => boolean;
+};
+
+const INITIAL_OPEN = 4;
+const INITIAL_RESOLVED = 1;
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+export function App({ pulses }: { pulses: ShiftPulses }) {
+  const open = pulses.open();
+  const resolved = pulses.resolved();
+  const priority = pulses.priority();
+
+  return (
+    <Screen title="Live Shift/Ticket Counter">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Live Shift/Ticket Counter</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Shift/Ticket Counter</Text>
+        <Text>{`Open tickets: ${open}`}</Text>
+        <Text>{`Resolved this shift: ${resolved}`}</Text>
+        <Text>{`Priority lane: ${priority ? "active" : "normal"}`}</Text>
+        <Text>{`Workload: ${open > 5 || priority ? "watch closely" : "steady"}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>A add ticket   D resolve ticket   P priority lane   R reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModulePulsesDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const [openTickets, setOpenTickets] = createPulse(INITIAL_OPEN);
+  const [resolvedTickets, setResolvedTickets] = createPulse(INITIAL_RESOLVED);
+  const [priorityActive, setPriorityActive] = createPulse(false);
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  function reset() {
+    setOpenTickets(INITIAL_OPEN);
+    setResolvedTickets(INITIAL_RESOLVED);
+    setPriorityActive(false);
+  }
+
+  session = mountTerminal(<App pulses={{ open: openTickets, resolved: resolvedTickets, priority: priorityActive }} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 16,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "a", command: { id: "tickets.add" }, scope: "global" },
+        { key: "A", command: { id: "tickets.add" }, scope: "global" },
+        { key: "d", command: { id: "tickets.resolve" }, scope: "global" },
+        { key: "D", command: { id: "tickets.resolve" }, scope: "global" },
+        { key: "p", command: { id: "tickets.priority" }, scope: "global" },
+        { key: "P", command: { id: "tickets.priority" }, scope: "global" },
+        { key: "r", command: { id: "tickets.reset" }, scope: "global" },
+        { key: "R", command: { id: "tickets.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "tickets.add") {
+          setOpenTickets((value) => value + 1);
+          return true;
+        }
+        if (command.id === "tickets.resolve") {
+          setOpenTickets((value) => Math.max(0, value - 1));
+          setResolvedTickets((value) => value + 1);
+          return true;
+        }
+        if (command.id === "tickets.priority") {
+          setPriorityActive((value) => !value);
+          return true;
+        }
+        if (command.id === "tickets.reset") {
+          reset();
+          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 running;
+    },
+    destroy() {
+      running = false;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModulePulsesDemo({ runtime: "headless", cols: 92, rows: 16 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModulePulsesDemo();
+  }
+}

package/examples/docs/module-query.tsx

@@ -0,0 +1,209 @@
+import { QueryClient } from "valyrian.js/query";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+interface InventoryItem {
+  sku: string;
+  name: string;
+  category: string;
+  stock: number;
+}
+
+interface InventoryResult {
+  readLabel: string;
+  items: InventoryItem[];
+}
+
+interface QueryState {
+  value: string;
+  status: string;
+  invalidated: boolean;
+  fetchCount: number;
+  selectedIndex: number;
+  items: InventoryItem[];
+  running: boolean;
+}
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+const INVENTORY: InventoryItem[] = [
+  { sku: "OPS-100", name: "Battery pack", category: "Operations", stock: 12 },
+  { sku: "NET-210", name: "Switch kit", category: "Network", stock: 4 },
+  { sku: "SEC-404", name: "Seal tags", category: "Security", stock: 30 }
+];
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function selectedItem(state: QueryState) {
+  return state.items[state.selectedIndex] || null;
+}
+
+export function App({ state }: { state: QueryState }) {
+  const item = selectedItem(state);
+  return (
+    <Screen title="Cached Inventory Browser">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Cached Inventory Browser</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Inventory Browser: fetches local stock data through a Valyrian query cache.</Text>
+        <Text>{`Query status: ${state.status}`}</Text>
+        <Text>{`Cached value: ${state.value}`}</Text>
+        <Text>{`Invalidated: ${state.invalidated ? "yes" : "no"}`}</Text>
+        <Text>{`Fetcher calls: ${state.fetchCount}`}</Text>
+        <Text>{`Selected item: ${item ? `${item.name} (${item.sku})` : "none"}`}</Text>
+        <Text>{`Category: ${item ? item.category : "none"}`}</Text>
+        <Text>{`Stock on hand: ${item ? item.stock : 0}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>F: fetch inventory   I: invalidate cache   J/K: select item   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleQueryDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: QueryState = {
+    value: "none",
+    status: "idle",
+    invalidated: false,
+    fetchCount: 0,
+    selectedIndex: 0,
+    items: [],
+    running: true
+  };
+  const client = new QueryClient({ staleTime: 30000, cacheTime: 1000 });
+  const query = client.query({
+    key: ["docs", "inventory"],
+    fetcher: (): InventoryResult => {
+      state.fetchCount += 1;
+      return {
+        readLabel: `terminal read #${state.fetchCount}`,
+        items: INVENTORY.map((item) => ({ ...item }))
+      };
+    }
+  });
+  let session: TerminalSession;
+
+  async function fetchInventory() {
+    state.status = "loading";
+    session.update();
+    const data = await query.fetch();
+    state.value = data?.readLabel || "none";
+    state.items = data?.items || [];
+    state.selectedIndex = Math.min(state.selectedIndex, Math.max(state.items.length - 1, 0));
+    state.status = query.state.status;
+    session.update();
+  }
+
+  function invalidateInventory() {
+    query.invalidate();
+    state.status = query.state.status;
+    state.invalidated = true;
+    session.update();
+  }
+
+  function moveSelection(delta: number) {
+    if (state.items.length === 0) {
+      return;
+    }
+    state.selectedIndex = (state.selectedIndex + delta + state.items.length) % state.items.length;
+    session.update();
+  }
+
+  function quit() {
+    state.running = false;
+    client.clear();
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 16,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "f", command: { id: "query.fetch" }, scope: "global" },
+        { key: "F", command: { id: "query.fetch" }, scope: "global" },
+        { key: "i", command: { id: "query.invalidate" }, scope: "global" },
+        { key: "I", command: { id: "query.invalidate" }, scope: "global" },
+        { key: "j", command: { id: "inventory.next" }, scope: "global" },
+        { key: "J", command: { id: "inventory.next" }, scope: "global" },
+        { key: "k", command: { id: "inventory.previous" }, scope: "global" },
+        { key: "K", command: { id: "inventory.previous" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "query.fetch") {
+          void fetchInventory();
+          return true;
+        }
+        if (command.id === "query.invalidate") {
+          invalidateInventory();
+          return true;
+        }
+        if (command.id === "inventory.next") {
+          moveSelection(1);
+          return true;
+        }
+        if (command.id === "inventory.previous") {
+          moveSelection(-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;
+      client.clear();
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleQueryDemo({ runtime: "headless", cols: 92, rows: 16 });
+    demo.dispatchKey("F");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("J");
+    demo.dispatchKey("I");
+    demo.dispatchKey("F");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleQueryDemo();
+  }
+}

package/examples/docs/module-request.tsx

@@ -0,0 +1,194 @@
+import { request } from "valyrian.js/request";
+import { Pane, Screen, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession } from "@valyrianjs/terminal";
+
+interface ModuleDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+interface RequestState {
+  status: "idle" | "loading" | "success" | "error";
+  message: string;
+  fetchedPath: string;
+  lastError: string;
+  failNext: boolean;
+  history: Array<"success" | "error">;
+  running: boolean;
+}
+
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function createState(): RequestState {
+  return {
+    status: "idle",
+    message: "Ready to check the service status",
+    fetchedPath: "none",
+    lastError: "none",
+    failNext: false,
+    history: [],
+    running: true
+  };
+}
+
+function historySummary(history: RequestState["history"]) {
+  return history.length === 0 ? "none" : history.join(" -> ");
+}
+
+const api = request.new("http://terminal.local", { allowedMethods: ["get"] });
+
+async function withFakeFetch<T>(shouldFail: boolean, run: () => Promise<T>) {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = ((input: RequestInfo | URL) => {
+    const url = new URL(String(input));
+    if (shouldFail) {
+      return Promise.resolve(
+        new Response(JSON.stringify({ message: "controlled local failure" }), { status: 503 })
+      );
+    }
+    return Promise.resolve(
+      new Response(JSON.stringify({ status: "ok", path: `${url.pathname}${url.search}` }), { status: 200 })
+    );
+  }) as typeof fetch;
+
+  try {
+    return await run();
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+}
+
+export function App({ state }: { state: RequestState }) {
+  return (
+    <Screen title="Service Status Client">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Service Status Client</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Status Client: checks a local service endpoint without using the network.</Text>
+        <Text>{`Request status: ${state.status}`}</Text>
+        <Text>{state.message}</Text>
+        <Text>{`Fetched: ${state.fetchedPath}`}</Text>
+        <Text>{`Last error: ${state.lastError}`}</Text>
+        <Text>{`Next request: ${state.failNext ? "controlled error" : "success"}`}</Text>
+        <Text>{`History: ${historySummary(state.history)}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>R: refresh status   E: force next error   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleRequestDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state = createState();
+  let session: TerminalSession;
+
+  async function loadStatus() {
+    if (state.status === "loading") {
+      state.message = "Refresh already in progress";
+      session.update();
+      return;
+    }
+
+    state.status = "loading";
+    state.message = "Loading local service status";
+    session.update();
+    try {
+      const shouldFail = state.failNext;
+      state.failNext = false;
+      const body = (await withFakeFetch(shouldFail, () => api.get("/status", { page: 1 }))) as { status: string; path: string };
+      state.status = "success";
+      state.history.push("success");
+      state.message = state.lastError === "none" ? `HTTP status: ${body.status}` : `Retry result: ${body.status}`;
+      state.fetchedPath = body.path;
+    } catch (error) {
+      state.status = "error";
+      state.history.push("error");
+      state.message = error instanceof Error ? error.message : "Request failed";
+      state.lastError = state.message;
+      state.fetchedPath = "/status?page=1";
+    }
+    session.update();
+  }
+
+  function quit() {
+    state.running = false;
+    session.destroy();
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 16,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "r", command: { id: "request.load" }, scope: "global" },
+        { key: "R", command: { id: "request.load" }, scope: "global" },
+        { key: "e", command: { id: "request.failNext" }, scope: "global" },
+        { key: "E", command: { id: "request.failNext" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "request.load") {
+          void loadStatus();
+          return true;
+        }
+        if (command.id === "request.failNext") {
+          state.failNext = true;
+          state.message = "Next refresh will use the controlled error path";
+          session.update();
+          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 = createModuleRequestDemo({ runtime: "headless", cols: 92, rows: 16 });
+    demo.dispatchKey("E");
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleRequestDemo();
+  }
+}