@valyrianjs/terminal 0.2.1 → 0.2.3

package/examples/docs/module-valyrian-core.tsx

@@ -0,0 +1,159 @@
+import { v } from "valyrian.js";
+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 Command = {
+  id: string;
+  name: string;
+  result: string;
+};
+
+type CommandPaletteState = {
+  selected: number;
+  result: string;
+  history: string[];
+};
+
+const COMMANDS: Command[] = [
+  { id: "open-incidents", name: "Open incident board", result: "Incident board opened" },
+  { id: "assign-oncall", name: "Assign on-call engineer", result: "On-call engineer assigned" },
+  { id: "publish-summary", name: "Publish shift summary", result: "Shift summary published" }
+];
+
+const INITIAL_RESULT = "Choose a command";
+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 clampSelection(index: number) {
+  return (index + COMMANDS.length) % COMMANDS.length;
+}
+
+const manualNode = v(Text, null, "Manual vnode: quick actions are composed with TSX rows");
+
+export function App({ state }: { state: CommandPaletteState }) {
+  return (
+    <Screen title="Terminal Command Palette">
+      <Text style={{ color: "#ffffff", background: "#020617" }}>Terminal Command Palette</Text>
+      <Pane style={PANEL_STYLE}>
+        <Text>Command Palette</Text>
+        {manualNode}
+        {COMMANDS.map((command, index) => (
+          <Text>{`${index === state.selected ? ">" : " "} ${command.name}`}</Text>
+        ))}
+        <Text>{`Result: ${state.result}`}</Text>
+        <Text>{`History: ${state.history.length ? state.history.join(" -> ") : "none"}`}</Text>
+      </Pane>
+      <Text style={FOOTER_STYLE}>J/K move   Enter run command   R reset   Ctrl+C: quit</Text>
+    </Screen>
+  );
+}
+
+export function createModuleValyrianCoreDemo(options: TerminalMountOptions = {}): ModuleDemo {
+  const state: CommandPaletteState = { selected: 0, result: INITIAL_RESULT, history: [] };
+  let running = true;
+  let session: TerminalSession;
+
+  function quit() {
+    running = false;
+    session.destroy();
+  }
+
+  function runSelectedCommand() {
+    const command = COMMANDS[state.selected];
+    state.result = command.result;
+    state.history = [...state.history.slice(-2), command.name];
+  }
+
+  function reset() {
+    state.selected = 0;
+    state.result = INITIAL_RESULT;
+    state.history = [];
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: options.cols ?? 92,
+    rows: options.rows ?? 18,
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "j", command: { id: "palette.next" }, scope: "global" },
+        { key: "J", command: { id: "palette.next" }, scope: "global" },
+        { key: "k", command: { id: "palette.previous" }, scope: "global" },
+        { key: "K", command: { id: "palette.previous" }, scope: "global" },
+        { key: "ENTER", command: { id: "palette.run" }, scope: "global" },
+        { key: "r", command: { id: "palette.reset" }, scope: "global" },
+        { key: "R", command: { id: "palette.reset" }, scope: "global" },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "palette.next") {
+          state.selected = clampSelection(state.selected + 1);
+          return true;
+        }
+        if (command.id === "palette.previous") {
+          state.selected = clampSelection(state.selected - 1);
+          return true;
+        }
+        if (command.id === "palette.run") {
+          runSelectedCommand();
+          return true;
+        }
+        if (command.id === "palette.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 = createModuleValyrianCoreDemo({ runtime: "headless", cols: 92, rows: 18 });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createModuleValyrianCoreDemo();
+  }
+}

package/examples/docs/pizza-builder.tsx

@@ -0,0 +1,463 @@
+import { Button, Fixed, Input, Pane, Screen, Split, Text, mountTerminal } from "@valyrianjs/terminal";
+import type { TerminalMountOptions, TerminalSession, TerminalTheme } from "@valyrianjs/terminal";
+
+type LayoutMode = "wide" | "medium" | "compact";
+
+interface Ingredient {
+  id: string;
+  name: string;
+  category: string;
+  price: number;
+}
+
+interface PizzaBuilderState {
+  cursorIndex: number;
+  selectedIds: Set<string>;
+  orderName: string;
+  layoutMode: LayoutMode;
+  warning: string;
+  confirmed: boolean;
+  confirmationId: string;
+  terminalCols: number;
+  terminalRows: number;
+  running: boolean;
+}
+
+export interface PizzaBuilderDemo {
+  session: TerminalSession;
+  dispatchKey(key: string): string;
+  output(): string;
+  ansiOutput(): string;
+  isRunning(): boolean;
+  destroy(): void;
+}
+
+const BASE_PRICE = 8;
+const INGREDIENTS: Ingredient[] = [
+  { id: "mozzarella", name: "Mozzarella", category: "Cheese", price: 1.5 },
+  { id: "pepperoni", name: "Pepperoni", category: "Meat", price: 2 },
+  { id: "mushrooms", name: "Mushrooms", category: "Veg", price: 1.25 },
+  { id: "olives", name: "Olives", category: "Veg", price: 1 },
+  { id: "basil", name: "Basil", category: "Herb", price: 0.75 },
+  { id: "hot-honey", name: "Hot honey", category: "Finish", price: 1.25 }
+];
+
+const SNAPSHOT_SIZE = { cols: 120, rows: 34 };
+const COMPACT_MAX_COLS = 60;
+const MEDIUM_MAX_COLS = 90;
+
+const APP_SHELL_STYLE = { color: "#f5f5f5", background: "#0f0f0f" };
+const APP_FOOTER_STYLE = { color: "#d4d4d4", background: "#1a1a1a" };
+const INGREDIENTS_PANEL_STYLE = {
+  color: "#f5f5f5",
+  background: "#1a1a1a",
+  padding: { left: 1, right: 1 }
+};
+const SUMMARY_PANEL_STYLE = {
+  color: "#f5f5f5",
+  background: "#151515",
+  padding: { left: 1, right: 1 }
+};
+const CHECKOUT_PANEL_STYLE = {
+  color: "#f5f5f5",
+  background: "#1a140f",
+  padding: { left: 1, right: 1 }
+};
+const ROW_CURRENT_STYLE = { color: "#ffffff", background: "#243b32" };
+const ROW_SELECTED_STYLE = { color: "#ffffff", background: "#4a2f16" };
+const ROW_IDLE_STYLE = { color: "#d4d4d4" };
+const TOTAL_VALUE_STYLE = { color: "#ffffff", background: "#005f4f" };
+const CHECKOUT_READY_STYLE = { color: "#ffffff", background: "#2e2600" };
+const MUTED_COPY_STYLE = { color: "#a3a3a3" };
+const WARNING_STYLE = { color: "#ffffff", background: "#7c2d12" };
+const SUCCESS_STYLE = { color: "#ffffff", background: "#166534" };
+const PIZZA_THEME: TerminalTheme = {
+  spans: {
+    focus: {
+      background: "#1f2328"
+    }
+  }
+};
+
+function createInitialState(size: { cols: number; rows: number }): PizzaBuilderState {
+  return {
+    cursorIndex: 0,
+    selectedIds: new Set(),
+    orderName: "",
+    layoutMode: layoutModeForCols(size.cols),
+    warning: "",
+    confirmed: false,
+    confirmationId: "",
+    terminalCols: size.cols,
+    terminalRows: size.rows,
+    running: true
+  };
+}
+
+function layoutModeForCols(cols: number): LayoutMode {
+  if (cols <= COMPACT_MAX_COLS) return "compact";
+  if (cols <= MEDIUM_MAX_COLS) return "medium";
+  return "wide";
+}
+
+function shouldRunSnapshot() {
+  return process.argv.includes("--snapshot") || process.env.VALYRIAN_TERMINAL_EXAMPLE_SNAPSHOT === "1" || !process.stdin.isTTY;
+}
+
+function formatPrice(value: number) {
+  return `$${value.toFixed(2)}`;
+}
+
+function selectedIngredients(state: PizzaBuilderState) {
+  return INGREDIENTS.filter((ingredient) => state.selectedIds.has(ingredient.id));
+}
+
+function totalPrice(state: PizzaBuilderState) {
+  let total = BASE_PRICE;
+  for (const ingredient of INGREDIENTS) {
+    if (state.selectedIds.has(ingredient.id)) {
+      total += ingredient.price;
+    }
+  }
+  return total;
+}
+
+function confirmOrder(state: PizzaBuilderState) {
+  if (state.orderName.trim().length === 0) {
+    state.warning = "Add a name for this order before checkout.";
+    state.confirmed = false;
+    state.confirmationId = "";
+    return;
+  }
+  state.warning = "";
+  state.confirmed = true;
+  state.confirmationId = "PIZZA-1001";
+}
+
+function layoutLabel(mode: LayoutMode) {
+  if (mode === "medium") return "Vista media";
+  if (mode === "compact") return "Vista compacta";
+  return "Vista amplia: ingredientes, resumen y checkout";
+}
+
+function layoutSize(mode: LayoutMode) {
+  if (mode === "medium") return { cols: 84, rows: 30 };
+  if (mode === "compact") return { cols: 52, rows: 34 };
+  return SNAPSHOT_SIZE;
+}
+
+function initialTerminalSize(options: TerminalMountOptions) {
+  if (isTerminalDimension(options.cols) && isTerminalDimension(options.rows)) {
+    return { cols: options.cols, rows: options.rows };
+  }
+
+  if (isTerminalDimension(options.stdout?.columns) && isTerminalDimension(options.stdout?.rows)) {
+    return { cols: options.stdout.columns, rows: options.stdout.rows };
+  }
+
+  if (shouldRunSnapshot()) {
+    return SNAPSHOT_SIZE;
+  }
+
+  return { cols: process.stdout.columns, rows: process.stdout.rows };
+}
+
+function isTerminalDimension(value: number | undefined): value is number {
+  return Number.isInteger(value) && Number(value) >= 1;
+}
+
+export function App({ state }: { state: PizzaBuilderState }) {
+  const selected = selectedIngredients(state);
+  const total = totalPrice(state);
+  return (
+    <Screen title="Pizza Builder">
+      <Fixed position="top" size={4}>
+        <Pane fill style={APP_SHELL_STYLE}>
+          <Text>Pizza Builder</Text>
+          <Text>{`${layoutLabel(state.layoutMode)}  Terminal: ${state.terminalCols}x${state.terminalRows}`}</Text>
+          <Text state="muted" styles={{ muted: MUTED_COPY_STYLE }}>Build a pizza, review the total, and finish with a local demo checkout.</Text>
+        </Pane>
+      </Fixed>
+      <Split
+        fill
+        direction="row"
+        gap={0}
+        sizes={["2fr", "1fr", "1fr"]}
+        breakpoints={[
+          { maxCols: COMPACT_MAX_COLS, direction: "column", sizes: ["2fr", "1fr", "1fr"], gap: 0 },
+          { maxCols: MEDIUM_MAX_COLS, sizes: ["3fr", "2fr", "2fr"], gap: 0 }
+        ]}
+      >
+        <Pane id="ingredients-list" focusable style={INGREDIENTS_PANEL_STYLE}>
+          <Text>Ingredients | toppings</Text>
+          <Text state="muted" styles={{ muted: MUTED_COPY_STYLE }}>Use Up/Down to choose ingredients, then Space to select.</Text>
+          {INGREDIENTS.map((ingredient, index) => {
+            const marker = index === state.cursorIndex ? ">" : " ";
+            const selectedMark = state.selectedIds.has(ingredient.id) ? "[•]" : "[ ]";
+            const rowState = index === state.cursorIndex ? "current" : state.selectedIds.has(ingredient.id) ? "selected" : undefined;
+            return <Text state={rowState} style={rowState ? undefined : ROW_IDLE_STYLE} styles={{ current: ROW_CURRENT_STYLE, selected: ROW_SELECTED_STYLE }}>{`${marker} ${selectedMark} ${ingredient.name}  ${ingredient.category}  ${formatPrice(ingredient.price)}`}</Text>;
+          })}
+        </Pane>
+        <Pane style={SUMMARY_PANEL_STYLE}>
+          <Text>Order summary</Text>
+          <Text>{`Base pizza: ${formatPrice(BASE_PRICE)}`}</Text>
+          <Text>{selected.length === 0 ? "No toppings selected" : "Selected toppings:"}</Text>
+          {selected.map((ingredient) => (
+            <Text>{`- ${ingredient.name}  ${formatPrice(ingredient.price)}`}</Text>
+          ))}
+          <Text style={TOTAL_VALUE_STYLE}>{`Total: ${formatPrice(total)}`}</Text>
+        </Pane>
+        <Pane style={CHECKOUT_PANEL_STYLE}>
+          <Text>Simulated checkout</Text>
+          <Text>{`Order name: ${state.orderName}`}</Text>
+          <Input
+            id="order-name"
+            value={state.orderName}
+            placeholder="Type a name"
+            onchange={(event) => {
+              state.orderName = event.value;
+              state.warning = "";
+              state.confirmed = false;
+              state.confirmationId = "";
+            }}
+          />
+          <Text>Payment method: demo card</Text>
+          <Text state="muted" styles={{ muted: MUTED_COPY_STYLE }}>No real payment is processed</Text>
+          <Text state={state.warning ? "warning" : state.confirmed ? "success" : undefined} style={!state.warning && !state.confirmed ? CHECKOUT_READY_STYLE : undefined} styles={{ warning: WARNING_STYLE, success: SUCCESS_STYLE }}>{state.warning || (state.confirmed ? "Confirmed" : "Press Enter on Confirm to finish.")}</Text>
+          <Text>{state.confirmationId ? `Confirmation: ${state.confirmationId}` : "Confirmation: pending"}</Text>
+          <Button id="confirm-order" onpress={() => confirmOrder(state)}>Confirm demo checkout</Button>
+        </Pane>
+      </Split>
+      <Fixed position="bottom" size={2}>
+        <Pane fill style={APP_FOOTER_STYLE}>
+          <Text>{state.warning || (state.confirmed ? `Confirmed  Confirmation: ${state.confirmationId}` : "Ready for your order")}</Text>
+          <Text>Space: toggle ingredient   Enter: next field/finish   Tab: move focus   R: resize   C: clear   Ctrl+C: quit</Text>
+        </Pane>
+      </Fixed>
+    </Screen>
+  );
+}
+
+export function createPizzaBuilderDemo(options: TerminalMountOptions = {}): PizzaBuilderDemo {
+  const initialSize = initialTerminalSize(options);
+  const state = createInitialState(initialSize);
+  let session: TerminalSession;
+  let cleanupOutputResize: (() => void) | null = null;
+
+  function resizeSession(size: { cols: number; rows: number }) {
+    state.terminalCols = size.cols;
+    state.terminalRows = size.rows;
+    state.layoutMode = layoutModeForCols(size.cols);
+    session.resize(size.cols, size.rows);
+  }
+
+  function quit() {
+    state.running = false;
+    cleanupOutputResize?.();
+    cleanupOutputResize = null;
+    session.destroy();
+  }
+
+  function watchOutputResize() {
+    const stdout = options.stdout;
+    if (!stdout || typeof stdout.on !== "function") {
+      return;
+    }
+
+    const removeResizeListener = typeof stdout.off === "function" ? stdout.off.bind(stdout) : stdout.removeListener?.bind(stdout);
+    if (!removeResizeListener) {
+      return;
+    }
+
+    const onResize = () => {
+      const cols = stdout.columns;
+      const rows = stdout.rows;
+      if (!isTerminalDimension(cols) || !isTerminalDimension(rows)) {
+        return;
+      }
+
+      resizeSession({ cols, rows });
+    };
+
+    try {
+      stdout.on("resize", onResize);
+    } catch {
+      return;
+    }
+
+    cleanupOutputResize = () => removeResizeListener("resize", onResize);
+  }
+
+  function moveCursor(step: number) {
+    state.cursorIndex = (state.cursorIndex + step + INGREDIENTS.length) % INGREDIENTS.length;
+  }
+
+  function toggleIngredient() {
+    const ingredient = INGREDIENTS[state.cursorIndex];
+    if (state.selectedIds.has(ingredient.id)) {
+      state.selectedIds.delete(ingredient.id);
+    } else {
+      state.selectedIds.add(ingredient.id);
+    }
+    state.confirmed = false;
+    state.confirmationId = "";
+  }
+
+  function resizeDemo() {
+    if (state.layoutMode === "wide") {
+      resizeSession(layoutSize("medium"));
+      return;
+    }
+    if (state.layoutMode === "medium") {
+      resizeSession(layoutSize("compact"));
+      return;
+    }
+    resizeSession(initialSize);
+  }
+
+  function resetOrder() {
+    state.cursorIndex = 0;
+    state.selectedIds.clear();
+    state.orderName = "";
+    state.warning = "";
+    state.confirmed = false;
+    state.confirmationId = "";
+    resizeSession(initialSize);
+  }
+
+  function clearOrder() {
+    resetOrder();
+    session.focus("ingredients-list");
+  }
+
+  function completeCheckout() {
+    confirmOrder(state);
+    if (state.warning) {
+      session.focus("order-name");
+      return;
+    }
+    resetOrder();
+    session.focus("ingredients-list");
+  }
+
+  session = mountTerminal(<App state={state} />, {
+    ...options,
+    cols: initialSize.cols,
+    rows: initialSize.rows,
+    theme: {
+      styles: options.theme?.styles,
+      spans: {
+        ...PIZZA_THEME.spans,
+        ...options.theme?.spans
+      }
+    },
+    keymap: {
+      ...options.keymap,
+      bindings: [
+        ...(options.keymap?.bindings || []),
+        { key: "UP", command: { id: "ingredients.prev" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: "ARROWUP", command: { id: "ingredients.prev" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: "k", command: { id: "ingredients.prev" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: "DOWN", command: { id: "ingredients.next" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: "ARROWDOWN", command: { id: "ingredients.next" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: "j", command: { id: "ingredients.next" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: "ENTER", command: { id: "focus.orderName" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: "SPACE", command: { id: "ingredients.toggle" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: " ", command: { id: "ingredients.toggle" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: "r", command: { id: "layout.resize" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: "R", command: { id: "layout.resize" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: "c", command: { id: "order.clear" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: "C", command: { id: "order.clear" }, scope: "focus", when: { focusedId: "ingredients-list" } },
+        { key: "UP", command: { id: "ingredients.prev" }, scope: "focus", when: { focusedId: "confirm-order" } },
+        { key: "ARROWUP", command: { id: "ingredients.prev" }, scope: "focus", when: { focusedId: "confirm-order" } },
+        { key: "k", command: { id: "ingredients.prev" }, scope: "focus", when: { focusedId: "confirm-order" } },
+        { key: "DOWN", command: { id: "ingredients.next" }, scope: "focus", when: { focusedId: "confirm-order" } },
+        { key: "ARROWDOWN", command: { id: "ingredients.next" }, scope: "focus", when: { focusedId: "confirm-order" } },
+        { key: "j", command: { id: "ingredients.next" }, scope: "focus", when: { focusedId: "confirm-order" } },
+        { key: "ENTER", command: { id: "order.complete" }, scope: "button", when: { focusedId: "confirm-order" } },
+        { key: " ", command: { id: "button.press" }, scope: "button", when: { focusedId: "confirm-order" } },
+        { key: "r", command: { id: "layout.resize" }, scope: "focus", when: { focusedId: "confirm-order" } },
+        { key: "R", command: { id: "layout.resize" }, scope: "focus", when: { focusedId: "confirm-order" } },
+        { key: "c", command: { id: "order.clear" }, scope: "focus", when: { focusedId: "confirm-order" } },
+        { key: "C", command: { id: "order.clear" }, scope: "focus", when: { focusedId: "confirm-order" } },
+        { key: "ENTER", command: { id: "focus.confirmOrder" }, scope: "input", when: { focusedId: "order-name" } },
+        { key: "CTRL_C", command: { id: "quit" }, scope: "global" }
+      ],
+      onCommand(command, context) {
+        if (command.id === "ingredients.prev") {
+          moveCursor(-1);
+          return true;
+        }
+        if (command.id === "ingredients.next") {
+          moveCursor(1);
+          return true;
+        }
+        if (command.id === "ingredients.toggle") {
+          toggleIngredient();
+          return true;
+        }
+        if (command.id === "layout.resize") {
+          resizeDemo();
+          return true;
+        }
+        if (command.id === "focus.orderName") {
+          session.focus("order-name");
+          return true;
+        }
+        if (command.id === "focus.confirmOrder") {
+          session.focus("confirm-order");
+          return true;
+        }
+        if (command.id === "order.complete") {
+          completeCheckout();
+          return true;
+        }
+        if (command.id === "order.clear") {
+          clearOrder();
+          return true;
+        }
+        if (command.id === "quit") {
+          quit();
+          return true;
+        }
+        return options.keymap?.onCommand?.(command, context);
+      }
+    }
+  });
+
+  session.focus("ingredients-list");
+  watchOutputResize();
+
+  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;
+      cleanupOutputResize?.();
+      cleanupOutputResize = null;
+      session.destroy();
+    }
+  };
+}
+
+if (import.meta.main) {
+  if (shouldRunSnapshot()) {
+    const demo = createPizzaBuilderDemo({ runtime: "headless", ...SNAPSHOT_SIZE });
+    process.stdout.write(demo.output());
+    process.stdout.write("\n");
+    demo.destroy();
+  } else {
+    createPizzaBuilderDemo();
+  }
+}