@pablozaiden/terminatui 0.1.2 → 0.3.0-beta-1

package/src/tui/context/LogsContext.tsx

@@ -0,0 +1,35 @@
+import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from "react";
+import { AppContext } from "../../core/context.ts";
+import type { LogEvent } from "../../core/logger.ts";
+
+interface LogsContextValue {
+    logs: LogEvent[];
+}
+
+const LogsContext = createContext<LogsContextValue | null>(null);
+
+export function LogsProvider({ children }: { children: ReactNode }) {
+    const [logs, setLogs] = useState<LogEvent[]>([]);
+
+    useEffect(() => {
+        const unsubscribe = AppContext.current.logger.onLogEvent((event: LogEvent) => {
+            setLogs((prev) => [...prev, event]);
+        });
+
+        return () => {
+            unsubscribe?.();
+        };
+    }, []);
+
+    const value = useMemo(() => ({ logs }), [logs]);
+
+    return <LogsContext.Provider value={value}>{children}</LogsContext.Provider>;
+}
+
+export function useLogs(): LogsContextValue {
+    const context = useContext(LogsContext);
+    if (!context) {
+        throw new Error("useLogs must be used within LogsProvider");
+    }
+    return context;
+}

package/src/tui/context/NavigationContext.tsx

@@ -0,0 +1,194 @@
+import {
+    createContext,
+    useContext,
+    useMemo,
+    useReducer,
+    useRef,
+    useCallback,
+    type ReactNode,
+} from "react";
+
+export interface ScreenEntry<TParams = unknown> {
+    route: string;
+    params?: TParams;
+    meta?: { focus?: string; breadcrumb?: string[] };
+}
+
+export interface ModalEntry<TParams = unknown> {
+    id: string;
+    params?: TParams;
+}
+
+/**
+ * Back handler function.
+ * Return true if handled, false to let navigation handle it.
+ */
+export type BackHandler = () => boolean;
+
+export interface NavigationAPI {
+    current: ScreenEntry;
+    stack: ScreenEntry[];
+    push: <TParams>(route: string, params?: TParams, meta?: ScreenEntry["meta"]) => void;
+    replace: <TParams>(route: string, params?: TParams, meta?: ScreenEntry["meta"]) => void;
+    reset: <TParams>(route: string, params?: TParams, meta?: ScreenEntry["meta"]) => void;
+    pop: () => void;
+    canGoBack: boolean;
+
+    modalStack: ModalEntry[];
+    currentModal?: ModalEntry;
+    openModal: <TParams>(id: string, params?: TParams) => void;
+    closeModal: () => void;
+    hasModal: boolean;
+
+    /**
+     * Handle back/escape.
+     * 1. If modal is open, closes modal
+     * 2. Otherwise, calls the registered back handler (if any)
+     * 3. If no handler or handler returns false, pops the stack
+     */
+    goBack: () => void;
+
+    /**
+     * Register a back handler for the current screen.
+     * The handler is called when goBack() is invoked (after closing modals).
+     * Return true from the handler if it handled the back action.
+     */
+    setBackHandler: (handler: BackHandler | null) => void;
+}
+
+type NavigationProviderProps<TParams = unknown> = {
+    initialScreen: ScreenEntry<TParams>;
+    children: ReactNode;
+    /** Called when we can't go back anymore (at root with empty stack) */
+    onExit?: () => void;
+};
+
+type NavigationAction =
+    | { type: "push"; screen: ScreenEntry }
+    | { type: "replace"; screen: ScreenEntry }
+    | { type: "reset"; screen: ScreenEntry }
+    | { type: "pop" }
+    | { type: "openModal"; modal: ModalEntry }
+    | { type: "closeModal" };
+
+type NavigationState = {
+    stack: ScreenEntry[];
+    modalStack: ModalEntry[];
+};
+
+function navigationReducer(
+    state: NavigationState,
+    action: NavigationAction
+): NavigationState {
+    switch (action.type) {
+        case "push":
+            return { ...state, stack: [...state.stack, action.screen] };
+        case "replace": {
+            const nextStack = state.stack.length === 0
+                ? [action.screen]
+                : [...state.stack.slice(0, -1), action.screen];
+            return { ...state, stack: nextStack };
+        }
+        case "reset":
+            return { ...state, stack: [action.screen] };
+        case "pop": {
+            if (state.stack.length <= 1) return state;
+            return { ...state, stack: state.stack.slice(0, -1) };
+        }
+        case "openModal":
+            return { ...state, modalStack: [...state.modalStack, action.modal] };
+        case "closeModal": {
+            if (state.modalStack.length === 0) return state;
+            return { ...state, modalStack: state.modalStack.slice(0, -1) };
+        }
+        default:
+            return state;
+    }
+}
+
+const NavigationContext = createContext<NavigationAPI | null>(null);
+
+export function NavigationProvider<TParams = unknown>({
+    initialScreen,
+    children,
+    onExit,
+}: NavigationProviderProps<TParams>) {
+    const [state, dispatch] = useReducer(navigationReducer, {
+        stack: [initialScreen],
+        modalStack: [],
+    });
+
+    // Back handler ref - set by the current screen
+    const backHandlerRef = useRef<BackHandler | null>(null);
+
+    const setBackHandler = useCallback((handler: BackHandler | null) => {
+        backHandlerRef.current = handler;
+    }, []);
+
+    const api = useMemo<NavigationAPI>(() => {
+        const stack = state.stack;
+        const modalStack = state.modalStack;
+        const current = stack[stack.length - 1]!;
+        const currentModal = modalStack[modalStack.length - 1];
+
+        const goBack = () => {
+            // 1. If modal is open, close it
+            if (modalStack.length > 0) {
+                dispatch({ type: "closeModal" });
+                return;
+            }
+
+            // 2. Let the screen's back handler try first
+            if (backHandlerRef.current) {
+                const handled = backHandlerRef.current();
+                if (handled) {
+                    return;
+                }
+            }
+
+            // 3. Pop the stack if possible
+            if (stack.length > 1) {
+                dispatch({ type: "pop" });
+                return;
+            }
+
+            // 4. At root, call onExit
+            onExit?.();
+        };
+
+        return {
+            current,
+            stack,
+            push: <TParams,>(route: string, params?: TParams, meta?: ScreenEntry["meta"]) =>
+                dispatch({ type: "push", screen: { route, params, meta } }),
+            replace: <TParams,>(route: string, params?: TParams, meta?: ScreenEntry["meta"]) =>
+                dispatch({ type: "replace", screen: { route, params, meta } }),
+            reset: <TParams,>(route: string, params?: TParams, meta?: ScreenEntry["meta"]) =>
+                dispatch({ type: "reset", screen: { route, params, meta } }),
+            pop: () => dispatch({ type: "pop" }),
+            canGoBack: stack.length > 1 || modalStack.length > 0,
+            modalStack,
+            currentModal,
+            openModal: <TParams,>(id: string, params?: TParams) =>
+                dispatch({ type: "openModal", modal: { id, params } }),
+            closeModal: () => dispatch({ type: "closeModal" }),
+            hasModal: modalStack.length > 0,
+            goBack,
+            setBackHandler,
+        };
+    }, [state, onExit, setBackHandler]);
+
+    return (
+        <NavigationContext.Provider value={api}>
+            {children}
+        </NavigationContext.Provider>
+    );
+}
+
+export function useNavigation(): NavigationAPI {
+    const context = useContext(NavigationContext);
+    if (!context) {
+        throw new Error("useNavigation must be used within a NavigationProvider");
+    }
+    return context;
+}

package/src/tui/context/RendererContext.tsx

@@ -0,0 +1,20 @@
+import { createContext, useContext, type ReactNode } from "react";
+import type { Renderer } from "../adapters/types.ts";
+
+const RendererContext = createContext<Renderer | null>(null);
+
+export function RendererProvider({ renderer, children }: { renderer: Renderer; children: ReactNode }) {
+    return (
+        <RendererContext.Provider value={renderer}>
+            {children}
+        </RendererContext.Provider>
+    );
+}
+
+export function useRenderer(): Renderer {
+    const renderer = useContext(RendererContext);
+    if (!renderer) {
+        throw new Error("useRenderer must be used within RendererProvider");
+    }
+    return renderer;
+}

package/src/tui/context/TuiAppContext.tsx

@@ -0,0 +1,58 @@
+import {
+    createContext,
+    useContext,
+    type ReactNode,
+} from "react";
+import type { AnyCommand } from "../../core/command.ts";
+
+/**
+ * App-level context value - provides app info and commands to screens.
+ */
+export interface TuiAppContextValue {
+    /** Application name (used for persistence keys, CLI commands, etc.) */
+    name: string;
+    /** Display name for the header */
+    displayName?: string;
+    /** Application version */
+    version: string;
+    /** All available commands */
+    commands: AnyCommand[];
+    /** Exit the TUI application */
+    onExit: () => void;
+}
+
+const TuiAppContext = createContext<TuiAppContextValue | null>(null);
+
+interface TuiAppContextProviderProps extends TuiAppContextValue {
+    children: ReactNode;
+}
+
+/**
+ * Provider that gives screens access to app-level information.
+ */
+export function TuiAppContextProvider({
+    children,
+    name,
+    displayName,
+    version,
+    commands,
+    onExit,
+}: TuiAppContextProviderProps) {
+    return (
+        <TuiAppContext.Provider value={{ name, displayName, version, commands, onExit }}>
+            {children}
+        </TuiAppContext.Provider>
+    );
+}
+
+/**
+ * Access the TUI app context.
+ * @throws Error if used outside of TuiAppContextProvider
+ */
+export function useTuiApp(): TuiAppContextValue {
+    const context = useContext(TuiAppContext);
+    if (!context) {
+        throw new Error("useTuiApp must be used within a TuiAppContextProvider");
+    }
+    return context;
+}

package/src/tui/hooks/useActiveKeyHandler.ts

@@ -0,0 +1,75 @@
+import { useEffect, useId, useRef } from "react";
+import { useKeyboardContext } from "../context/KeyboardContext.tsx";
+import type { KeyHandler } from "../adapters/types.ts";
+
+interface UseActiveKeyHandlerOptions {
+    /**
+     * Whether the handler is currently enabled.
+     * When false, the handler is unregistered.
+     * @default true
+     */
+    enabled?: boolean;
+}
+
+/**
+ * Register as the active keyboard handler.
+ * 
+ * Only ONE handler is active at a time - the most recently registered enabled handler.
+ * When a modal opens and calls this hook, it becomes the active handler.
+ * When it unmounts or becomes disabled, the previous handler is restored.
+ * 
+ * The handler receives keys AFTER global shortcuts (Ctrl+L, Ctrl+Y, Esc) are processed.
+ * Return true from the handler if the key was handled.
+ * 
+ * @param handler - Callback invoked on keyboard events. Return true if handled.
+ * @param options - Optional configuration (e.g., enabled flag).
+ * 
+ * @example
+ * ```tsx
+ * // In a screen component
+ * useActiveKeyHandler((event) => {
+ *     if (event.name === "return" || event.name === "enter") {
+ *         onSelect();
+ *         return true;
+ *     }
+ *     return false;
+ * });
+ * 
+ * // In a modal - becomes active when visible
+ * useActiveKeyHandler(
+ *     (event) => {
+ *         if (event.name === "escape") {
+ *             onClose();
+ *             return true;
+ *         }
+ *         return false;
+ *     },
+ *     { enabled: visible }
+ * );
+ * ```
+ */
+export function useActiveKeyHandler(
+    handler: KeyHandler,
+    options: UseActiveKeyHandlerOptions = {}
+): void {
+    const { enabled = true } = options;
+    const { setActiveHandler } = useKeyboardContext();
+    const id = useId();
+    const handlerRef = useRef(handler);
+    
+    // Keep ref updated without triggering re-registration
+    handlerRef.current = handler;
+
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+
+        // Register a stable wrapper that calls the current handler
+        const unregister = setActiveHandler(id, (event) => handlerRef.current(event));
+        return unregister;
+    }, [id, enabled, setActiveHandler]);
+}
+
+// Re-export types for convenience
+export type { KeyHandler };

package/src/tui/hooks/useBackHandler.ts

@@ -0,0 +1,34 @@
+import { useEffect } from "react";
+import { useNavigation, type BackHandler } from "../context/NavigationContext.tsx";
+
+/**
+ * Register a back handler for the current screen.
+ * 
+ * When the user presses Esc (or calls navigation.goBack()), this handler
+ * is called. Return true if you handled the back action, false to let
+ * navigation proceed with default behavior (pop stack or exit).
+ * 
+ * The handler is automatically unregistered when the component unmounts.
+ * 
+ * @example
+ * ```tsx
+ * // In a screen with special back behavior
+ * useBackHandler(() => {
+ *     if (hasUnsavedChanges) {
+ *         showConfirmDialog();
+ *         return true; // We handled it
+ *     }
+ *     return false; // Let navigation pop
+ * });
+ * ```
+ */
+export function useBackHandler(handler: BackHandler): void {
+    const navigation = useNavigation();
+
+    useEffect(() => {
+        navigation.setBackHandler(handler);
+        return () => {
+            navigation.setBackHandler(null);
+        };
+    }, [navigation, handler]);
+}

package/src/tui/hooks/useClipboard.ts

@@ -1,39 +1,55 @@
 import { useCallback, useState } from "react";
 import * as fs from "fs";
 
-/**
- * Copy text to clipboard using OSC 52 escape sequence.
- * Write directly to /dev/tty to bypass any stdout interception.
- */
+
 function copyWithOsc52(text: string): boolean {
     try {
-        // Strip ANSI codes if Bun is available, otherwise use as-is
-        const cleanText = typeof Bun !== "undefined" 
-            ? Bun.stripANSI(text) 
-            : text.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "");
+        const cleanText = Bun.stripANSI(text);
         const base64 = Buffer.from(cleanText).toString("base64");
-        // OSC 52 sequence: ESC ] 52 ; c ; <base64> BEL
         const osc52 = `\x1b]52;c;${base64}\x07`;
-        
-        // Try to write directly to the TTY to bypass OpenTUI's stdout capture
+
         try {
-            const fd = fs.openSync('/dev/tty', 'w');
+            const fd = fs.openSync("/dev/tty", "w");
             fs.writeSync(fd, osc52);
             fs.closeSync(fd);
         } catch {
-            // Fallback to stdout if /dev/tty is not available
             process.stdout.write(osc52);
         }
-        
+
         return true;
     } catch {
         return false;
     }
 }
 
+async function copyWithPbcopy(text: string): Promise<boolean> {
+    try {
+        const cleanText = Bun.stripANSI(text);
+        const proc = Bun.spawn(["pbcopy"], {
+            stdin: "pipe",
+            stdout: "ignore",
+            stderr: "ignore",
+        });
+
+        proc.stdin.write(cleanText);
+        proc.stdin.end();
+
+        const exitCode = await proc.exited;
+        return exitCode === 0;
+    } catch {
+        return false;
+    }
+}
+
+export async function copyToClipboard(text: string): Promise<boolean> {
+    if (process.env["TERM_PROGRAM"] === "Apple_Terminal") {
+        return await copyWithPbcopy(text);
+    }
+
+    return copyWithOsc52(text);
+}
+
 export interface UseClipboardResult {
-    /** Copy text to clipboard */
-    copy: (text: string) => boolean;
     /** Last action message for status display */
     lastAction: string;
     /** Set the last action message */
@@ -48,19 +64,18 @@ export interface UseClipboardResult {
  */
 export function useClipboard(): UseClipboardResult {
     const [lastAction, setLastAction] = useState("");
-    
-    const copy = useCallback((text: string): boolean => {
-        return copyWithOsc52(text);
-    }, []);
 
     const copyWithMessage = useCallback((text: string, label: string) => {
-        const success = copyWithOsc52(text);
-        if (success) {
+        void (async () => {
+            const success = await copyToClipboard(text);
+            if (!success) {
+                return;
+            }
+
             setLastAction(`✓ ${label} copied to clipboard`);
-            // Clear message after 2 seconds
             setTimeout(() => setLastAction(""), 2000);
-        }
+        })();
     }, []);
 
-    return { copy, lastAction, setLastAction, copyWithMessage };
+    return { lastAction, setLastAction, copyWithMessage };
 }

package/src/tui/hooks/useClipboardProvider.ts

@@ -0,0 +1,42 @@
+import { useEffect, useId } from "react";
+import { useClipboardContext, type ClipboardContent, type ClipboardProvider } from "../context/ClipboardContext.tsx";
+
+/**
+ * Hook for registering a clipboard provider.
+ * The provider is automatically registered when mounted and unregistered when unmounted.
+ * 
+ * @param provider - Function that returns clipboard content or null
+ * @param enabled - Whether the provider is active (default: true)
+ * 
+ * @example
+ * ```tsx
+ * // In a screen component
+ * useClipboardProvider(() => ({
+ *     content: JSON.stringify(values, null, 2),
+ *     label: "Config"
+ * }));
+ * 
+ * // In a modal that may or may not have content
+ * useClipboardProvider(() => {
+ *     if (!hasContent) return null;
+ *     return { content: data, label: "Modal Data" };
+ * });
+ * ```
+ */
+export function useClipboardProvider(
+    provider: ClipboardProvider,
+    enabled: boolean = true
+): void {
+    const { register } = useClipboardContext();
+    const id = useId();
+
+    useEffect(() => {
+        if (!enabled) return;
+
+        const unregister = register(id, provider);
+        return unregister;
+    }, [id, provider, enabled, register]);
+}
+
+// Re-export types for convenience
+export type { ClipboardContent, ClipboardProvider };

package/src/tui/hooks/useGlobalKeyHandler.ts

@@ -0,0 +1,54 @@
+import { useEffect, useRef } from "react";
+import { useKeyboardContext, type GlobalKeyHandler } from "../context/KeyboardContext.tsx";
+
+/**
+ * Set the global keyboard handler.
+ * 
+ * The global handler receives ALL key events FIRST, before the active handler.
+ * Use this for app-wide shortcuts like Ctrl+L (logs), Ctrl+Y (copy), Esc (back).
+ * 
+ * Return true from the handler if the key was handled (prevents active handler from receiving it).
+ * 
+ * Only ONE global handler is supported - typically set by the main app component.
+ * 
+ * @param handler - Callback invoked on all keyboard events. Return true if handled.
+ * 
+ * @example
+ * ```tsx
+ * // In TuiRoot
+ * useGlobalKeyHandler((event) => {
+ *     const key = event;
+ *     
+ *     if (key.ctrl && key.name === "l") {
+ *         toggleLogs();
+ *         return true;
+ *     }
+ *     
+ *     if (key.name === "escape") {
+ *         handleBack();
+ *         return true;
+ *     }
+ *     
+ *     return false; // Let active handler process
+ * });
+ * ```
+ */
+export function useGlobalKeyHandler(handler: GlobalKeyHandler): void {
+    const { setGlobalHandler } = useKeyboardContext();
+    const handlerRef = useRef(handler);
+    
+    // Keep ref updated without triggering re-registration
+    handlerRef.current = handler;
+
+    useEffect(() => {
+        // Set a stable wrapper that calls the current handler
+        const unregister = setGlobalHandler((event) => handlerRef.current(event));
+
+        return () => {
+            unregister();
+        };
+    }, [setGlobalHandler]);
+}
+
+// Re-export types for convenience
+export type { GlobalKeyHandler };

package/src/tui/modals/CliModal.tsx

@@ -0,0 +1,82 @@
+import { useActiveKeyHandler } from "../hooks/useActiveKeyHandler.ts";
+import { Container } from "../semantic/Container.tsx";
+import { ScrollView } from "../semantic/ScrollView.tsx";
+import { ModalBase } from "../components/ModalBase.tsx";
+import { useClipboardProvider } from "../hooks/useClipboardProvider.ts";
+import { Label } from "../semantic/Label.tsx";
+import { Value } from "../semantic/Value.tsx";
+import type { ModalComponent, ModalDefinition } from "../registry.ts";
+
+export interface CliModalParams {
+    command: string;
+}
+
+export class CliModal implements ModalDefinition<CliModalParams> {
+    static readonly Id = "cli";
+
+    getId(): string {
+        return CliModal.Id;
+    }
+
+    component(): ModalComponent<CliModalParams> {
+        return function CliModalComponentWrapper({ params, onClose }: { params: CliModalParams; onClose: () => void; }) {
+            return (
+                <CliModalView
+                    command={params.command}
+                    visible={true}
+                    onClose={onClose}
+                />
+            );
+        };
+    }
+}
+
+interface CliModalViewProps extends CliModalParams {
+    /** Whether the modal is visible */
+    visible: boolean;
+    /** Called when the modal should close */
+    onClose: () => void;
+}
+
+/**
+ * Modal displaying the CLI command equivalent of the current config.
+ */
+function CliModalView({
+    command,
+    visible,
+    onClose,
+}: CliModalViewProps) {
+    // Register clipboard provider for CLI command
+    useClipboardProvider(
+        () => ({ content: command, label: "CLI" }),
+        visible
+    );
+
+    // Handle Enter to close (Esc is handled globally)
+    useActiveKeyHandler(
+        (event) => {
+            if (event.name === "return" || event.name === "enter") {
+                onClose();
+                return true;
+            }
+            return false;
+        },
+        { enabled: visible }
+    );
+
+    if (!visible) {
+        return null;
+    }
+
+    return (
+        <ModalBase title="CLI Command" width="80%" height={10} top={4} left={4}>
+            <ScrollView axis="horizontal" height={3}>
+                <Container>
+                    <Value>{command}</Value>
+                </Container>
+            </ScrollView>
+
+            <Label color="mutedText">Enter or Esc to close</Label>
+        </ModalBase>
+    );
+}