giggles 0.3.15 → 0.3.17

package/README.md

@@ -10,6 +10,19 @@ giggles is a batteries-included react framework for building terminal apps. buil
 
 inspired by the [charmbracelet](https://github.com/charmbracelet) ecosystem, it comes with a rich set of UI components, hooks for focus and navigation management, and terminal utilities for things like running shell commands.
 
+## features
+
+- no `useInput` hooks scattered across your app — focus, input routing, and keyboard navigation are handled for you
+- navigate between views with a simple API; the previously focused component is restored when you return
+- a full set of hooks and components — `useFocus`, `FocusGroup`, `FocusTrap`, `useNavigation`, and more — for building any interaction pattern without reimplementing the plumbing
+- built-in keybinding registry so your app can always show users what keys do what, in the current context — context-aware and accessible via a hook
+- a component library covering most TUI use cases, from text inputs and autocomplete to virtual lists for large datasets — with sensible defaults and render props for full customization
+- render markdown in the terminal, with full formatting and syntax-highlighted code block and diff support
+- hand off terminal control to external programs like `vim` or `less` and reclaim it cleanly when they exit, or spawn processes and stream their output directly into your UI
+- a consistent look out of the box, customizable from a single theme object
+
+## your first TUI
+
 to get started, run
 
 ```bash

package/dist/terminal/index.d.ts

@@ -1,3 +1,4 @@
+import { SpawnOptionsWithoutStdio } from 'child_process';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 
@@ -5,6 +6,25 @@ type TerminalSize = {
     rows: number;
     columns: number;
 };
+type SpawnOptions = SpawnOptionsWithoutStdio & {
+    /**
+     * Inject FORCE_COLOR=1 and TERM=xterm-256color into the child process
+     * environment so tools that detect isTTY emit ANSI color codes.
+     */
+    pty?: boolean;
+};
+type SpawnOutputLine = {
+    type: 'stdout' | 'stderr';
+    data: string;
+};
+type SpawnHandle = {
+    output: SpawnOutputLine[];
+    running: boolean;
+    exitCode: number | null;
+    error: Error | null;
+    run: (command: string, args?: string[], options?: SpawnOptions) => void;
+    kill: () => void;
+};
 
 declare function useTerminalSize(): TerminalSize;
 
@@ -22,4 +42,6 @@ declare function useShellOut(): {
     }>;
 };
 
-export { AlternateScreen, type TerminalSize, useShellOut, useTerminalFocus, useTerminalSize };
+declare function useSpawn(): SpawnHandle;
+
+export { AlternateScreen, type SpawnHandle, type SpawnOptions, type SpawnOutputLine, type TerminalSize, useShellOut, useSpawn, useTerminalFocus, useTerminalSize };

package/dist/terminal/index.js

@@ -54,9 +54,88 @@ function useShellOut() {
     run
   };
 }
+
+// src/terminal/hooks/useSpawn.ts
+import { spawn } from "child_process";
+import { useCallback as useCallback2, useEffect as useEffect2, useRef as useRef2, useState as useState2 } from "react";
+function useSpawn() {
+  const [output, setOutput] = useState2([]);
+  const [running, setRunning] = useState2(false);
+  const [exitCode, setExitCode] = useState2(null);
+  const [error, setError] = useState2(null);
+  const processRef = useRef2(null);
+  const cancelRef = useRef2(null);
+  useEffect2(() => {
+    return () => {
+      var _a, _b;
+      (_a = cancelRef.current) == null ? void 0 : _a.call(cancelRef);
+      (_b = processRef.current) == null ? void 0 : _b.kill();
+    };
+  }, []);
+  const run = useCallback2((command, args, options) => {
+    var _a, _b;
+    (_a = cancelRef.current) == null ? void 0 : _a.call(cancelRef);
+    (_b = processRef.current) == null ? void 0 : _b.kill();
+    processRef.current = null;
+    cancelRef.current = null;
+    let cancelled = false;
+    cancelRef.current = () => {
+      cancelled = true;
+    };
+    const { pty, ...spawnOptions } = options ?? {};
+    setOutput([]);
+    setRunning(true);
+    setExitCode(null);
+    setError(null);
+    const env = pty ? { ...process.env, FORCE_COLOR: "1", TERM: "xterm-256color", ...spawnOptions.env } : { ...process.env, ...spawnOptions.env };
+    let proc;
+    try {
+      proc = spawn(command, args ?? [], { ...spawnOptions, env, stdio: "pipe" });
+    } catch (err) {
+      setRunning(false);
+      setError(err instanceof Error ? err : new Error(String(err)));
+      cancelRef.current = null;
+      return;
+    }
+    processRef.current = proc;
+    proc.stdout.on("data", (data) => {
+      if (!cancelled) setOutput((prev) => [...prev, { type: "stdout", data: data.toString() }]);
+    });
+    proc.stderr.on("data", (data) => {
+      if (!cancelled) setOutput((prev) => [...prev, { type: "stderr", data: data.toString() }]);
+    });
+    proc.on("error", (err) => {
+      if (!cancelled) {
+        cancelled = true;
+        setError(err);
+        setRunning(false);
+        processRef.current = null;
+        cancelRef.current = null;
+      }
+    });
+    proc.on("close", (code) => {
+      if (!cancelled) {
+        setRunning(false);
+        setExitCode(code);
+        processRef.current = null;
+        cancelRef.current = null;
+      }
+    });
+  }, []);
+  const kill = useCallback2(() => {
+    var _a, _b;
+    (_a = cancelRef.current) == null ? void 0 : _a.call(cancelRef);
+    cancelRef.current = null;
+    (_b = processRef.current) == null ? void 0 : _b.kill();
+    processRef.current = null;
+    setRunning(false);
+  }, []);
+  return { output, running, exitCode, error, run, kill };
+}
 export {
   AlternateScreen,
   useShellOut,
+  useSpawn,
   useTerminalFocus,
   useTerminalSize
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "giggles",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "license": "MIT",
   "repository": {
     "type": "git",