@valyrianjs/terminal 0.2.0 → 0.2.2

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();
+  }
+}

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();
+  }
+}