@pablozaiden/terminatui 0.3.0-beta-1 → 0.4.0

package/src/tui/context/KeyboardContext.tsx

@@ -1,132 +0,0 @@
-import {
-    createContext,
-    useContext,
-    useCallback,
-    useEffect,
-    useMemo,
-    useRef,
-    type ReactNode,
-} from "react";
-import type { KeyboardEvent, KeyHandler } from "../adapters/types.ts";
-import { useRenderer } from "./RendererContext.tsx";
-
-function useRendererKeyboard() {
-    return useRenderer().keyboard;
-}
-
-
-export type GlobalKeyHandler = (event: KeyboardEvent) => boolean;
-
-interface KeyboardContextValue {
-    /**
-     * 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);
-
-interface KeyboardProviderProps {
-    children: ReactNode;
-}
-
-/**
- * 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 keyboard = useRendererKeyboard();
-
-    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);
-        };
-    }, []);
-
-    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;
-            }
-
-            if (inputCapturedRef.current) {
-                return false;
-            }
-
-            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={value}>
-            {children}
-        </KeyboardContext.Provider>
-    );
-}
-
-/**
- * Access the keyboard context.
- * @throws Error if used outside of KeyboardProvider
- */
-export function useKeyboardContext(): KeyboardContextValue {
-    const context = useContext(KeyboardContext);
-    if (!context) {
-        throw new Error("useKeyboardContext must be used within a KeyboardProvider");
-    }
-    return context;
-}

package/src/tui/hooks/useActiveKeyHandler.ts

@@ -1,75 +0,0 @@
-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/useClipboard.ts

@@ -1,81 +0,0 @@
-import { useCallback, useState } from "react";
-import * as fs from "fs";
-
-
-function copyWithOsc52(text: string): boolean {
-    try {
-        const cleanText = Bun.stripANSI(text);
-        const base64 = Buffer.from(cleanText).toString("base64");
-        const osc52 = `\x1b]52;c;${base64}\x07`;
-
-        try {
-            const fd = fs.openSync("/dev/tty", "w");
-            fs.writeSync(fd, osc52);
-            fs.closeSync(fd);
-        } catch {
-            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 {
-    /** Last action message for status display */
-    lastAction: string;
-    /** Set the last action message */
-    setLastAction: (action: string) => void;
-    /** Copy and set a success message */
-    copyWithMessage: (text: string, label: string) => void;
-}
-
-/**
- * Hook for clipboard operations using OSC 52.
- * Works in most modern terminal emulators.
- */
-export function useClipboard(): UseClipboardResult {
-    const [lastAction, setLastAction] = useState("");
-
-    const copyWithMessage = useCallback((text: string, label: string) => {
-        void (async () => {
-            const success = await copyToClipboard(text);
-            if (!success) {
-                return;
-            }
-
-            setLastAction(`✓ ${label} copied to clipboard`);
-            setTimeout(() => setLastAction(""), 2000);
-        })();
-    }, []);
-
-    return { lastAction, setLastAction, copyWithMessage };
-}

package/src/tui/hooks/useClipboardProvider.ts

@@ -1,42 +0,0 @@
-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

@@ -1,54 +0,0 @@
-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

@@ -1,82 +0,0 @@
-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>
-    );
-}

package/src/tui/modals/EditorModal.tsx

@@ -1,207 +0,0 @@
-import { useState, useEffect } from "react";
-import type { FieldConfig } from "../components/types.ts";
-import { ModalBase } from "../components/ModalBase.tsx";
-import { useActiveKeyHandler } from "../hooks/useActiveKeyHandler.ts";
-import { Select } from "../semantic/Select.tsx";
-import { TextInput } from "../semantic/TextInput.tsx";
-import { Label } from "../semantic/Label.tsx";
-import type { ModalComponent, ModalDefinition } from "../registry.ts";
-import { useKeyboardContext } from "../context/KeyboardContext.tsx";
-
-export interface EditorModalParams {
-    fieldKey: string;
-    currentValue: unknown;
-    fieldConfigs: FieldConfig[];
-    onSubmit: (value: unknown) => void;
-    onCancel: () => void;
-}
-
-export class EditorModal implements ModalDefinition<EditorModalParams> {
-    static readonly Id = "property-editor";
-
-    getId(): string {
-        return EditorModal.Id;
-    }
-
-    component(): ModalComponent<EditorModalParams> {
-        return function EditorModalComponentWrapper({ params, onClose }: { params: EditorModalParams; onClose: () => void; }) {
-            return (
-                <EditorModalView
-                    fieldKey={params.fieldKey}
-                    currentValue={params.currentValue}
-                    visible={true}
-                    onSubmit={(value) => {
-                        params.onSubmit?.(value);
-                    }}
-                    onCancel={() => {
-                        params.onCancel?.();
-                        onClose();
-                    }}
-                    fieldConfigs={params.fieldConfigs}
-                />
-            );
-        };
-    }
-}
-
-interface EditorModalViewProps {
-    /** Whether the modal is visible */
-    visible: boolean;
-}
-
-/**
- * Modal for editing field values.
- * Supports text, number, enum, and boolean types.
- * 
- * Note: This modal uses native OpenTUI input/select components that handle
- * keyboard events internally. The modal registers as the active handler to
- * block the underlying screen from receiving events, even though most key
- * handling is done by the native components.
- */
-interface EditorModalViewProps extends EditorModalParams {
-    /** Whether the modal is visible */
-    visible: boolean;
-}
-
-function EditorModalView({
-    fieldKey,
-    currentValue,
-    visible,
-    onSubmit,
-    onCancel,
-    fieldConfigs,
-}: EditorModalViewProps) {
-    const { setInputCaptured } = useKeyboardContext();
-    const [inputValue, setInputValue] = useState("");
-    const [selectIndex, setSelectIndex] = useState(0);
-
-    // Reset state when field changes
-    useEffect(() => {
-        if (fieldKey && visible) {
-            setInputValue(String(currentValue ?? ""));
-
-            // For enums/booleans, find current index
-            const fieldConfig = fieldConfigs.find((f) => f.key === fieldKey);
-            if (fieldConfig?.type === "boolean") {
-                setSelectIndex(currentValue ? 1 : 0);
-            } else if (fieldConfig?.options) {
-                const idx = fieldConfig.options.findIndex((o) => o.value === currentValue);
-                setSelectIndex(idx >= 0 ? idx : 0);
-            }
-        }
-    }, [fieldKey, currentValue, visible, fieldConfigs]);
-
-    // While the editor is open, avoid extra per-keystroke work by preventing the
-    // underlying screen from receiving key events.
-    useEffect(() => {
-        if (!visible || !fieldKey) {
-            return;
-        }
-
-        setInputCaptured(true);
-        return () => {
-            setInputCaptured(false);
-        };
-    }, [visible, fieldKey, setInputCaptured]);
-
-    // Register as active handler to block underlying screen from receiving events.
-    // The native input/select components handle Enter internally via onSubmit/onSelect,
-    // so we don't need to handle it here.
-    useActiveKeyHandler(
-        (event) => {
-            if (event.name === "return" || event.name === "enter") {
-                return true;
-            }
-
-            if (event.name === "escape") {
-                onCancel();
-                return true;
-            }
-
-            return false;
-        },
-        { enabled: visible && Boolean(fieldKey) }
-    );
-
-    if (!visible || !fieldKey) {
-        return null;
-    }
-
-    const fieldConfig = fieldConfigs.find((f) => f.key === fieldKey);
-    if (!fieldConfig) {
-        return null;
-    }
-
-    const isNumber = fieldConfig.type === "number";
-
-    const handleInputSubmit = (value: string) => {
-        if (isNumber) {
-            onSubmit(parseInt(value.replace(/[^0-9-]/g, ""), 10) || 0);
-            onCancel();
-            return;
-        }
-
-        onSubmit(value);
-        onCancel();
-    };
-
-    const selectOptions =
-        fieldConfig.type === "boolean"
-            ? [
-                  { label: "False", value: "false" },
-                  { label: "True", value: "true" },
-              ]
-            : fieldConfig.type === "enum"
-              ? (fieldConfig.options ?? []).map((o) => ({
-                    label: o.name,
-                    value: String(o.value),
-                }))
-              : null;
-
-    const usesSelect = selectOptions !== null;
-
-    const handleSelectSubmit = () => {
-        const selected = selectOptions?.[selectIndex];
-        if (!selected) {
-            return;
-        }
-
-        if (fieldConfig.type === "boolean") {
-            onSubmit(selected.value === "true");
-            onCancel();
-            return;
-        }
-
-        onSubmit(selected.value);
-        onCancel();
-    };
-
-    return (
-        <ModalBase title={`Edit: ${fieldConfig.label}`} width="60%" height={12} top={4} left={6}>
-            {usesSelect && selectOptions && (
-                <Select
-                    options={selectOptions}
-                    value={selectOptions[selectIndex]?.value ?? selectOptions[0]?.value ?? ""}
-                    focused={true}
-                    onChange={(next) => {
-                        const idx = selectOptions.findIndex((o) => o.value === next);
-                        setSelectIndex(idx >= 0 ? idx : 0);
-                    }}
-                    onSubmit={handleSelectSubmit}
-                />
-            )}
-
-            {!usesSelect && (
-                <TextInput
-                    value={inputValue}
-                    placeholder={fieldConfig.placeholder ?? `Enter ${fieldConfig.label.toLowerCase()}...`}
-                    focused={true}
-                    onChange={(value) => setInputValue(value)}
-                    onSubmit={() => handleInputSubmit(inputValue)}
-                />
-            )}
-
-            <Label color="mutedText">Enter to save, Esc to cancel</Label>
-        </ModalBase>
-    );
-}