@pablozaiden/terminatui 0.2.0 → 0.3.0

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

package/src/tui/modals/EditorModal.tsx

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

package/src/tui/modals/LogsModal.tsx

@@ -0,0 +1,98 @@
+import { useCallback } from "react";
+import { Container } from "../semantic/Container.tsx";
+import { ScrollView } from "../semantic/ScrollView.tsx";
+import { useActiveKeyHandler } from "../hooks/useActiveKeyHandler.ts";
+import { useClipboardProvider } from "../hooks/useClipboardProvider.ts";
+import { Label } from "../semantic/Label.tsx";
+import { LogColors } from "../components/logColors.ts";
+import { ModalBase } from "../components/ModalBase.tsx";
+import { useLogs } from "../context/LogsContext.tsx";
+import type { ModalComponent, ModalDefinition } from "../registry.ts";
+import { LogLevel } from "../../core/logger.ts";
+
+export interface LogsModalParams {}
+
+export class LogsModal implements ModalDefinition<LogsModalParams> {
+    static readonly Id = "logs";
+
+    getId(): string {
+        return LogsModal.Id;
+    }
+
+    component(): ModalComponent<LogsModalParams> {
+        return function LogsModalComponentWrapper({ params: _params, onClose }: { params: LogsModalParams; onClose: () => void; }) {
+            return (
+                <LogsModalView
+                    visible={true}
+                    onClose={onClose}
+                />
+            );
+        };
+    }
+}
+
+interface LogsModalViewProps {
+    /** Whether the panel is visible */
+    visible: boolean;
+    /** Callback when the modal is closed */
+    onClose: () => void;
+}
+
+/**
+ * Panel displaying log entries with color-coded levels.
+ */
+function LogsModalView({
+    visible,
+    onClose,
+}: LogsModalViewProps) {
+    const { logs } = useLogs();
+    // Handle Enter to close (Esc and Ctrl+L are handled globally)
+    useActiveKeyHandler(
+        (event) => {
+            if (event.name === "return" || event.name === "enter") {
+                onClose();
+                return true;
+            }
+            return false;
+        },
+        { enabled: visible }
+    );
+
+    // Register clipboard provider - logs content takes precedence when modal is open
+    useClipboardProvider(
+        useCallback(() => ({
+            content: logs.map((l) => l.message).join("\n"),
+            label: "Logs",
+        }), [logs]),
+        visible
+    );
+
+    if (!visible) {
+        return null;
+    }
+
+    const title = `Logs - ${logs.length}`;
+
+    return (
+        <ModalBase title={title} top={4} bottom={4} left={4} right={4}>
+            <ScrollView axis="vertical" flex={1} stickyToEnd={true} focused={true}>
+                <Container flexDirection="column" gap={0}>
+                    {logs.map((log, idx) => {
+                        const color = LogColors[log.level] ?? LogColors[LogLevel.info];
+                        const sanitized = Bun.stripANSI(log.message).trim();
+
+                        return (
+                            <Label key={`${log.timestamp.getTime()}-${idx}`}>
+                                <span fg={color}>{sanitized}</span>
+                            </Label>
+                        );
+                    })}
+
+                    {logs.length === 0 && (
+                        <Label color="mutedText">No logs yet...</Label>
+                    )}
+                </Container>
+            </ScrollView>
+        </ModalBase>
+    );
+}