@pablozaiden/terminatui 0.2.0 → 0.3.0-beta-1

package/src/tui/context/ExecutorContext.tsx

@@ -0,0 +1,139 @@
+import {
+    createContext,
+    useContext,
+    useCallback,
+    useState,
+    useRef,
+    type ReactNode,
+} from "react";
+import type { AnyCommand, CommandResult } from "../../core/command.ts";
+import type { OptionSchema, OptionValues } from "../../types/command.ts";
+import { AbortError } from "../../core/command.ts";
+
+/**
+ * Outcome of command execution.
+ */
+export interface ExecutionOutcome {
+    success: boolean;
+    result?: CommandResult;
+    error?: Error;
+    cancelled?: boolean;
+}
+
+/**
+ * Executor context value - provides command execution capabilities to screens.
+ */
+export interface ExecutorContextValue {
+    /** Whether a command is currently executing */
+    isExecuting: boolean;
+    /** Execute a command with the given values */
+    execute: (command: AnyCommand, values: Record<string, unknown>) => Promise<ExecutionOutcome>;
+    /** Cancel the currently executing command */
+    cancel: () => void;
+    /** Reset executor state */
+    reset: () => void;
+}
+
+const ExecutorContext = createContext<ExecutorContextValue | null>(null);
+
+interface ExecutorProviderProps {
+    children: ReactNode;
+}
+
+/**
+ * Provider that gives screens access to command execution capabilities.
+ * Screens can execute commands, check execution state, and cancel execution.
+ */
+export function ExecutorProvider({ children }: ExecutorProviderProps) {
+    const [isExecuting, setIsExecuting] = useState(false);
+    const abortControllerRef = useRef<AbortController | null>(null);
+
+    const execute = useCallback(async (
+        command: AnyCommand,
+        values: Record<string, unknown>
+    ): Promise<ExecutionOutcome> => {
+        // Cancel any previous execution
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+        }
+
+        const abortController = new AbortController();
+        abortControllerRef.current = abortController;
+
+        setIsExecuting(true);
+
+        try {
+            // Build config if command supports it
+            let configOrValues: unknown = values;
+            if (command.buildConfig) {
+                configOrValues = await command.buildConfig(values as OptionValues<OptionSchema>);
+            }
+
+            // Execute the command
+            const result = await command.execute(
+                configOrValues as OptionValues<OptionSchema>,
+                { signal: abortController.signal }
+            );
+
+            // Check if aborted during execution
+            if (abortController.signal.aborted) {
+                return { success: false, cancelled: true };
+            }
+
+            return {
+                success: true,
+                result: result as CommandResult | undefined,
+            };
+        } catch (e) {
+            // Check for cancellation
+            if (
+                abortController.signal.aborted ||
+                e instanceof AbortError ||
+                (e instanceof Error && e.name === "AbortError")
+            ) {
+                return { success: false, cancelled: true };
+            }
+
+            const error = e instanceof Error ? e : new Error(String(e));
+            return { success: false, error };
+        } finally {
+            setIsExecuting(false);
+            if (abortControllerRef.current === abortController) {
+                abortControllerRef.current = null;
+            }
+        }
+    }, []);
+
+    const cancel = useCallback(() => {
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+            abortControllerRef.current = null;
+        }
+    }, []);
+
+    const reset = useCallback(() => {
+        if (abortControllerRef.current) {
+            abortControllerRef.current.abort();
+            abortControllerRef.current = null;
+        }
+        setIsExecuting(false);
+    }, []);
+
+    return (
+        <ExecutorContext.Provider value={{ isExecuting, execute, cancel, reset }}>
+            {children}
+        </ExecutorContext.Provider>
+    );
+}
+
+/**
+ * Access the executor context.
+ * @throws Error if used outside of ExecutorProvider
+ */
+export function useExecutor(): ExecutorContextValue {
+    const context = useContext(ExecutorContext);
+    if (!context) {
+        throw new Error("useExecutor must be used within an ExecutorProvider");
+    }
+    return context;
+}

package/src/tui/context/KeyboardContext.tsx

@@ -2,50 +2,43 @@ import {
     createContext,
     useContext,
     useCallback,
+    useEffect,
+    useMemo,
     useRef,
     type ReactNode,
 } from "react";
-import { useKeyboard } from "@opentui/react";
-import type { KeyEvent } from "@opentui/core";
+import type { KeyboardEvent, KeyHandler } from "../adapters/types.ts";
+import { useRenderer } from "./RendererContext.tsx";
 
-/**
- * Priority levels for keyboard event handlers.
- * Higher priority handlers are called first.
- */
-export enum KeyboardPriority {
-    /** Modal/overlay handlers - highest priority, intercept first */
-    Modal = 100,
-    /** Focused section handlers - handle section-specific keys */
-    Focused = 50,
-    /** Global handlers - app-wide shortcuts, lowest priority */
-    Global = 0,
+function useRendererKeyboard() {
+    return useRenderer().keyboard;
 }
 
-/**
- * Extended keyboard event with custom stop propagation.
- * Use `stopPropagation()` to prevent lower-priority handlers from receiving the event.
- * Use `key.preventDefault()` only when you want to also block OpenTUI primitives.
- */
-export interface KeyboardEvent {
-    /** The underlying OpenTUI KeyEvent */
-    key: KeyEvent;
-    /** Stop propagation to lower-priority handlers in our system */
-    stopPropagation: () => void;
-    /** Whether propagation was stopped */
-    stopped: boolean;
-}
-
-export type KeyboardHandler = (event: KeyboardEvent) => void;
 
-interface RegisteredHandler {
-    id: string;
-    handler: KeyboardHandler;
-    priority: KeyboardPriority;
-}
+export type GlobalKeyHandler = (event: KeyboardEvent) => boolean;
 
 interface KeyboardContextValue {
-    register: (id: string, handler: KeyboardHandler, priority: KeyboardPriority) => void;
-    unregister: (id: string) => void;
+    /**
+     * Set the active handler (only one at a time - the topmost screen/modal).
+     * Returns unregister function.
+     */
+    setActiveHandler: (id: string, handler: KeyHandler) => () => void;
+
+    /**
+     * Set the global handler (processed before active handler).
+     * Only one global handler is supported.
+     * Returns unregister function.
+     */
+    setGlobalHandler: (handler: GlobalKeyHandler) => () => void;
+
+    /**
+     * Temporarily capture input (e.g. while an Ink TextInput is focused).
+     *
+     * While captured, only the global handler can receive events; the active handler
+     * stack is skipped. This prevents screens from doing extra work on every
+     * character typed.
+     */
+    setInputCaptured: (captured: boolean) => void;
 }
 
 const KeyboardContext = createContext<KeyboardContextValue | null>(null);
@@ -55,58 +48,79 @@ interface KeyboardProviderProps {
 }
 
 /**
- * Provider that coordinates all keyboard handlers via a single useKeyboard call.
- * Handlers are invoked in descending priority order (highest first).
- * Propagation stops when a handler calls `stopPropagation()`.
+ * Provider that coordinates keyboard handling with a simple model:
+ * 1. Global handler processes keys first (for app-wide shortcuts like Ctrl+L, Ctrl+Y, Esc)
+ * 2. If not handled, the active handler (topmost screen/modal) gets the key
+ * 
+ * Only ONE active handler is registered at a time - when a modal opens, it becomes
+ * the active handler; when it closes, the previous handler is restored.
  */
 export function KeyboardProvider({ children }: KeyboardProviderProps) {
-    const handlersRef = useRef<RegisteredHandler[]>([]);
-
-    const register = useCallback(
-        (id: string, handler: KeyboardHandler, priority: KeyboardPriority) => {
-            // Remove existing handler with same id (if any)
-            handlersRef.current = handlersRef.current.filter((h) => h.id !== id);
-            // Add new handler
-            handlersRef.current.push({ id, handler, priority });
-            // Sort by priority descending (highest first)
-            handlersRef.current.sort((a, b) => b.priority - a.priority);
-        },
-        []
-    );
+    const keyboard = useRendererKeyboard();
 
-    const unregister = useCallback((id: string) => {
-        handlersRef.current = handlersRef.current.filter((h) => h.id !== id);
+    const handlerStackRef = useRef<{ id: string; handler: KeyHandler }[]>([]);
+    const globalHandlerRef = useRef<GlobalKeyHandler | null>(null);
+    const inputCapturedRef = useRef(false);
+
+    const setActiveHandler = useCallback((id: string, handler: KeyHandler) => {
+        handlerStackRef.current = handlerStackRef.current.filter((h) => h.id !== id);
+        handlerStackRef.current.push({ id, handler });
+
+        return () => {
+            handlerStackRef.current = handlerStackRef.current.filter((h) => h.id !== id);
+        };
     }, []);
 
-    // Single useKeyboard call that dispatches to all registered handlers
-    useKeyboard((key: KeyEvent) => {
-        // Create our wrapper event with custom stop propagation
-        const event: KeyboardEvent = {
-            key,
-            stopped: false,
-            stopPropagation() {
-                this.stopped = true;
-            },
+    const setGlobalHandler = useCallback((handler: GlobalKeyHandler) => {
+        const previous = globalHandlerRef.current;
+        globalHandlerRef.current = handler;
+
+        return () => {
+            globalHandlerRef.current = previous;
         };
+    }, []);
+
+    useEffect(() => {
+        const unregister = keyboard.setGlobalHandler((event: KeyboardEvent) => {
+            if (globalHandlerRef.current?.(event)) {
+                return true;
+            }
 
-        for (const { handler } of handlersRef.current) {
-            // Stop if our propagation was stopped or if preventDefault was called
-            if (event.stopped || key.defaultPrevented) {
-                break;
+            if (inputCapturedRef.current) {
+                return false;
             }
-            handler(event);
-        }
-    });
+
+            const activeHandler = handlerStackRef.current[handlerStackRef.current.length - 1];
+            if (activeHandler) {
+                return activeHandler.handler(event);
+            }
+
+            return false;
+        });
+
+        return () => {
+            unregister();
+        };
+    }, [keyboard]);
+
+    const setInputCaptured = useCallback((captured: boolean) => {
+        inputCapturedRef.current = captured;
+    }, []);
+
+    const value = useMemo<KeyboardContextValue>(
+        () => ({ setActiveHandler, setGlobalHandler, setInputCaptured }),
+        [setActiveHandler, setGlobalHandler, setInputCaptured]
+    );
 
     return (
-        <KeyboardContext.Provider value={{ register, unregister }}>
+        <KeyboardContext.Provider value={value}>
             {children}
         </KeyboardContext.Provider>
     );
 }
 
 /**
- * Access the keyboard context for handler registration.
+ * Access the keyboard context.
  * @throws Error if used outside of KeyboardProvider
  */
 export function useKeyboardContext(): KeyboardContextValue {

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