@valyrianjs/terminal 0.2.0 → 0.2.2

package/examples/docs/module-tasks.tsx

@@ -0,0 +1,223 @@
+import { Task } from "valyrian.js/tasks";
+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 TaskDemoState {
+  status: string;
+  result: string;
+  error: string;
+  currentJob: string;
+  seenStates: string[];
+  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 waitForControlledAsync(signal: AbortSignal) {
+  return new Promise<void>((resolve) => {
+    const timer = setTimeout(resolve, 20);
+    signal.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
+
+function syncTaskState(state: TaskDemoState, task: Task<string, string>) {
+  const snapshot = task.state;
+  state.status = snapshot.status;
+  state.result = snapshot.result ? `Result: ${snapshot.result}` : "Result: none";
+  state.error = snapshot.error instanceof Error ? `Error: ${snapshot.error.message}` : "Error: none";
+}
+
+function visibleTaskStates(states: string[]) {
+  const compact: string[] = [];
+  for (const status of states) {
+    if ((status === "cancelled" || status === "error") && compact[compact.length - 1] === "running") {
+      compact.pop();
+    }
+    if (compact[compact.length - 1] !== status) {
+      compact.push(status);
+    }
+  }
+  return compact.join(" -> ");
+}
+
+export function App({ state }: { state: TaskDemoState }) {
+  return (
+    <Screen title="Background Maintenance Runner">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Background Maintenance Runner</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Maintenance Runner: runs local cleanup work through a Valyrian Task.</Text>
+        <Text>{`Task status: ${state.status}`}</Text>
+        <Text>{`Maintenance job: ${state.currentJob}`}</Text>
+        <Text>{state.result}</Text>
+        <Text>{state.error}</Text>
+        <Text>{`Seen states: ${visibleTaskStates(state.seenStates)}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>R: run cleanup   C: cancel scan   X: controlled fail   Z: reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleTasksDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: TaskDemoState = {
+    status: "idle",
+    result: "Result: none",
+    error: "Error: none",
+    currentJob: "none",
+    seenStates: ["idle"],
+    running: true
+  };
+  const task = new Task<string, string>(async (label, { signal }) => {
+    if (label === "fail") {
+      throw new Error("controlled task failure");
+    }
+    if (label === "scan") {
+      await waitForControlledAsync(signal);
+      if (signal.aborted) return "Cancelled stale scan";
+    }
+    return `Completed ${label}`;
+  }, { strategy: "restartable" });
+  const rememberState = () => {
+    const status = task.state.status;
+    if (state.seenStates[state.seenStates.length - 1] !== status) {
+      state.seenStates.push(status);
+    }
+    syncTaskState(state, task);
+  };
+  const offTaskState = task.on("state", () => {
+    rememberState();
+    session?.update();
+  });
+  let session: TerminalSession;
+
+  function quit() {
+    state.running = false;
+    offTaskState();
+    task.reset();
+    session.destroy();
+  }
+
+  async function runTask(label: string, job: string) {
+    state.currentJob = job;
+    try {
+      rememberState();
+      await task.run(label);
+    } catch {
+      // The task state snapshot carries the controlled error message.
+    }
+    syncTaskState(state, task);
+    session.update();
+  }
+
+  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: "task.run" }, scope: "global" },
+        { key: "R", command: { id: "task.run" }, scope: "global" },
+        { key: "c", command: { id: "task.cancel" }, scope: "global" },
+        { key: "C", command: { id: "task.cancel" }, scope: "global" },
+        { key: "x", command: { id: "task.error" }, scope: "global" },
+        { key: "X", command: { id: "task.error" }, scope: "global" },
+        { key: "z", command: { id: "task.reset" }, scope: "global" },
+        { key: "Z", command: { id: "task.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "task.run") {
+          void runTask("cleanup", "nightly cleanup");
+          return true;
+        }
+        if (command.id === "task.cancel") {
+          state.currentJob = "stale scan";
+          void task.run("scan");
+          rememberState();
+          task.cancel();
+          rememberState();
+          session.update();
+          return true;
+        }
+        if (command.id === "task.error") {
+          void runTask("fail", "permission audit");
+          return true;
+        }
+        if (command.id === "task.reset") {
+          state.currentJob = "none";
+          task.reset();
+          rememberState();
+          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;
+      offTaskState();
+      task.reset();
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleTasksDemo({ runtime: "headless", cols: 92, rows: 16 });
+    demo.dispatchKey("R");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("C");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("X");
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    demo.dispatchKey("Z");
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleTasksDemo();
+  }
+}

package/examples/docs/module-translate.tsx

@@ -0,0 +1,194 @@
+import { getLang, setLang, setLog, setStoreStrategy, setTranslations, t } from "valyrian.js/translate";
+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 Ticket = { id: string; customer: string; status: "open" | "waiting" | "closed" };
+type SupportState = { selected: number; language: "en" | "es"; filter: "all" | "open" };
+
+const TICKETS: Ticket[] = [
+  { id: "T-104", customer: "Northwind", status: "open" },
+  { id: "T-118", customer: "Contoso", status: "waiting" },
+  { id: "T-130", customer: "Tailspin", status: "closed" }
+];
+const PANEL_STYLE = { color: "#f8fafc", background: "#111827", padding: { left: 1, right: 1 } };
+const FOOTER_STYLE = { color: "#dbeafe", background: "#1e293b" };
+let storedLanguage = "en";
+
+function configureTranslations() {
+  setLog(false);
+  setStoreStrategy({
+    get: () => storedLanguage,
+    set: (language) => {
+      storedLanguage = language;
+    }
+  });
+  setTranslations(
+    {
+      title: "Bilingual Support Console",
+      purpose: "Support Console",
+      language: "Language",
+      filter: "Filter",
+      selected: "Selected ticket",
+      all: "all tickets",
+      openOnly: "open only",
+      status: { open: "open", waiting: "waiting", closed: "closed" },
+      help: "L language   J/K select ticket   F filter status   Ctrl+C: quit"
+    },
+    {
+      es: {
+        title: "Bilingual Support Console",
+        purpose: "Consola de soporte",
+        language: "Idioma",
+        filter: "Filtro",
+        selected: "Ticket elegido",
+        all: "todos los tickets",
+        openOnly: "solo abiertos",
+        status: { open: "abierto", waiting: "en espera", closed: "cerrado" },
+        help: "L idioma   J/K elegir ticket   F filtrar estado   Ctrl+C: quit"
+      }
+    }
+  );
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function visibleTickets(filter: SupportState["filter"]) {
+  return filter === "open" ? TICKETS.filter((ticket) => ticket.status === "open") : TICKETS;
+}
+
+export function App({ state }: { state: SupportState }) {
+  setLang(state.language);
+  const tickets = visibleTickets(state.filter);
+  const selected = tickets[state.selected] || tickets[0];
+
+  return (
+    <Screen title="Bilingual Support Console">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>{t("title")}</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>{t("purpose")}</Text>
+        <Text>{`${t("language")}: ${state.language === "en" ? "English" : "Español"}`}</Text>
+        <Text>{`${t("filter")}: ${state.filter === "open" ? t("openOnly") : t("all")}`}</Text>
+        {tickets.map((ticket, index) => (
+          <Text>{`${index === state.selected ? ">" : " "} ${ticket.id} ${ticket.customer} — ${t(`status.${ticket.status}`)}`}</Text>
+        ))}
+        <Text>{`${t("selected")}: ${selected.id} ${selected.customer}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>{t("help")}</Text>
+    </Screen>
+  );
+}
+
+export function createModuleTranslateDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const previousLanguage = getLang();
+  configureTranslations();
+  const state: SupportState = { selected: 0, language: "en", filter: "all" };
+  setLang(state.language);
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    setLang(previousLanguage);
+    session.destroy();
+  }
+
+  function clampSelection() {
+    const count = visibleTickets(state.filter).length;
+    state.selected = Math.min(state.selected, Math.max(0, count - 1));
+  }
+
+  function move(delta: number) {
+    const count = visibleTickets(state.filter).length;
+    state.selected = (state.selected + delta + count) % count;
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 18,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "l", command: { id: "support.language" }, scope: "global" },
+        { key: "L", command: { id: "support.language" }, scope: "global" },
+        { key: "j", command: { id: "support.next" }, scope: "global" },
+        { key: "J", command: { id: "support.next" }, scope: "global" },
+        { key: "k", command: { id: "support.previous" }, scope: "global" },
+        { key: "K", command: { id: "support.previous" }, scope: "global" },
+        { key: "f", command: { id: "support.filter" }, scope: "global" },
+        { key: "F", command: { id: "support.filter" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "support.language") {
+          state.language = state.language === "en" ? "es" : "en";
+          setLang(state.language);
+          session.update();
+          return true;
+        }
+        if (command.id === "support.next") {
+          move(1);
+          return true;
+        }
+        if (command.id === "support.previous") {
+          move(-1);
+          return true;
+        }
+        if (command.id === "support.filter") {
+          state.filter = state.filter === "all" ? "open" : "all";
+          clampSelection();
+          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;
+      setLang(previousLanguage);
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createModuleTranslateDemo({ runtime: "headless", cols: 92, rows: 18 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleTranslateDemo();
+  }
+}

package/examples/docs/module-utils.tsx

@@ -0,0 +1,168 @@
+import { get, pick, set } from "valyrian.js/utils";
+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 AccountPayload = {
+  account: { name: string; plan: string; region?: string; owner: { name: string; email: string } };
+  usage: { seats: number; projects: number; lastLogin: string };
+  billing: { status: string; renewal: string };
+};
+type InspectorState = { selected: number; filter: "all" | "account"; record: AccountPayload };
+type FieldRow = { group: string; label: string; value: string };
+type AccountSummaryKey = "name" | "plan" | "region";
+
+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 createRecord(): AccountPayload {
+  const record: AccountPayload = {
+    account: { name: "Northwind", plan: "Team", owner: { name: "Ada Lovelace", email: "ada@example.test" } },
+    usage: { seats: 12, projects: 4, lastLogin: "2026-05-29" },
+    billing: { status: "current", renewal: "2026-06-15" }
+  };
+  set(record, "account.region", "MX");
+  return record;
+}
+
+function buildRows(record: AccountPayload, filter: InspectorState["filter"]): FieldRow[] {
+  const safeAccount = pick<AccountPayload["account"], AccountSummaryKey>(record.account, ["name", "plan", "region"]);
+  const rows = [
+    { group: "account", label: "Account", value: String(get(safeAccount, "name", "unknown")) },
+    { group: "account", label: "Plan", value: String(get(safeAccount, "plan", "none")) },
+    { group: "account", label: "Region", value: String(get(safeAccount, "region", "unknown")) },
+    { group: "owner", label: "Owner", value: String(get(record, "account.owner.name", "unknown")) },
+    { group: "usage", label: "Seats", value: String(get(record, "usage.seats", 0)) },
+    { group: "usage", label: "Projects", value: String(get(record, "usage.projects", 0)) },
+    { group: "billing", label: "Billing", value: String(get(record, "billing.status", "unknown")) }
+  ];
+  return filter === "account" ? rows.filter((row) => row.group === "account") : rows;
+}
+
+export function App({ state }: { state: InspectorState }) {
+  const rows = buildRows(state.record, state.filter);
+  const selected = rows[state.selected] || rows[0];
+
+  return (
+    <Screen title="Account Data Inspector">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Account Data Inspector</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Account Data Inspector</Text>
+        <Text>{`Filter: ${state.filter === "account" ? "account fields" : "all groups"}`}</Text>
+        {rows.map((row, index) => (
+          <Text>{`${index === state.selected ? ">" : " "} [${row.group}] ${row.label}: ${row.value}`}</Text>
+        ))}
+        <Text>{`Selected field: ${selected.label}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>J/K select field   F filter group   R reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleUtilsDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: InspectorState = { selected: 0, filter: "all", record: createRecord() };
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  function clampSelection() {
+    const count = buildRows(state.record, state.filter).length;
+    state.selected = Math.min(state.selected, Math.max(0, count - 1));
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 20,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "inspector.next" }, scope: "global" },
+        { key: "J", command: { id: "inspector.next" }, scope: "global" },
+        { key: "k", command: { id: "inspector.previous" }, scope: "global" },
+        { key: "K", command: { id: "inspector.previous" }, scope: "global" },
+        { key: "f", command: { id: "inspector.filter" }, scope: "global" },
+        { key: "F", command: { id: "inspector.filter" }, scope: "global" },
+        { key: "r", command: { id: "inspector.reset" }, scope: "global" },
+        { key: "R", command: { id: "inspector.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "inspector.next") {
+          const count = buildRows(state.record, state.filter).length;
+          state.selected = (state.selected + 1) % count;
+          return true;
+        }
+        if (command.id === "inspector.previous") {
+          const count = buildRows(state.record, state.filter).length;
+          state.selected = (state.selected - 1 + count) % count;
+          return true;
+        }
+        if (command.id === "inspector.filter") {
+          state.filter = state.filter === "all" ? "account" : "all";
+          clampSelection();
+          return true;
+        }
+        if (command.id === "inspector.reset") {
+          state.selected = 0;
+          state.filter = "all";
+          state.record = createRecord();
+          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 = createModuleUtilsDemo({ runtime: "headless", cols: 92, rows: 20 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleUtilsDemo();
+  }
+}