@pablozaiden/terminatui 0.1.2 → 0.3.0-beta-1

package/src/tui/adapters/opentui/keyboard.ts

@@ -0,0 +1,61 @@
+import { useKeyboard } from "@opentui/react";
+import type { KeyEvent } from "@opentui/core";
+import { useCallback, useMemo, useRef } from "react";
+import type { KeyboardAdapter, KeyboardEvent, KeyHandler } from "../types.ts";
+
+function normalizeKeyEvent(key: KeyEvent): KeyboardEvent {
+    return {
+        name: key.name,
+        sequence: key.sequence,
+        ctrl: key.ctrl,
+        shift: key.shift,
+        meta: key.meta,
+    };
+}
+
+export function useOpenTuiKeyboardAdapter(): KeyboardAdapter {
+    const handlerStackRef = useRef<{ id: string; handler: KeyHandler }[]>([]);
+    const globalHandlerRef = useRef<KeyHandler | null>(null);
+
+    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: KeyHandler) => {
+        const previous = globalHandlerRef.current;
+        globalHandlerRef.current = handler;
+
+        return () => {
+            globalHandlerRef.current = previous;
+        };
+    }, []);
+
+    useKeyboard((key: KeyEvent) => {
+        const event = normalizeKeyEvent(key);
+
+        if (globalHandlerRef.current) {
+            const handled = globalHandlerRef.current(event);
+            if (handled) {
+                return;
+            }
+        }
+
+        const activeHandler = handlerStackRef.current[handlerStackRef.current.length - 1];
+        if (activeHandler) {
+            activeHandler.handler(event);
+        }
+    });
+
+    return useMemo(
+        () => ({
+            setActiveHandler,
+            setGlobalHandler,
+        }),
+        [setActiveHandler, setGlobalHandler]
+    );
+}

package/src/tui/adapters/types.ts

@@ -0,0 +1,70 @@
+import type { ReactNode } from "react";
+import type {
+    ButtonProps,
+    CodeHighlightProps,
+    CodeProps,
+    ContainerProps,
+    FieldProps,
+    LabelProps,
+    MenuButtonProps,
+    MenuItemProps,
+    OverlayProps,
+    PanelProps,
+    ScrollViewProps,
+    SelectProps,
+    SpacerProps,
+    SpinnerProps,
+    TextInputProps,
+    ValueProps,
+} from "../semantic/types.ts";
+
+export interface KeyboardEvent {
+    name: string;
+    sequence?: string;
+    ctrl?: boolean;
+    shift?: boolean;
+    meta?: boolean;
+}
+
+export type KeyHandler = (event: KeyboardEvent) => boolean;
+
+export interface KeyboardAdapter {
+    setActiveHandler: (id: string, handler: KeyHandler) => () => void;
+    setGlobalHandler: (handler: KeyHandler) => () => void;
+}
+
+export interface RendererConfig {
+    useAlternateScreen?: boolean;
+}
+
+export interface RendererComponents {
+    Field: (props: FieldProps) => ReactNode;
+    Button: (props: ButtonProps) => ReactNode;
+    MenuButton: (props: MenuButtonProps) => ReactNode;
+    MenuItem: (props: MenuItemProps) => ReactNode;
+
+    Container: (props: ContainerProps) => ReactNode;
+    Panel: (props: PanelProps) => ReactNode;
+    ScrollView: (props: ScrollViewProps) => ReactNode;
+
+    Overlay: (props: OverlayProps) => ReactNode;
+    Spacer: (props: SpacerProps) => ReactNode;
+    Spinner: (props: SpinnerProps) => ReactNode;
+
+    Label: (props: LabelProps) => ReactNode;
+    Value: (props: ValueProps) => ReactNode;
+    Code: (props: CodeProps) => ReactNode;
+    CodeHighlight: (props: CodeHighlightProps) => ReactNode;
+
+    TextInput: (props: TextInputProps) => ReactNode;
+    Select: (props: SelectProps) => ReactNode;
+}
+
+export interface Renderer {
+    initialize: () => Promise<void>;
+    render: (node: ReactNode) => void;
+    destroy: () => void;
+
+    keyboard: KeyboardAdapter;
+    components: RendererComponents;
+}

package/src/tui/components/ActionButton.tsx

@@ -1,36 +0,0 @@
-import { Theme } from "../theme.ts";
-
-interface ActionButtonProps {
-    /** Button label */
-    label: string;
-    /** Whether this button is selected */
-    isSelected: boolean;
-    /** Optional spinner frame for loading state */
-    spinnerFrame?: string;
-}
-
-/**
- * Action button displayed at the bottom of a config form.
- */
-export function ActionButton({ label, isSelected, spinnerFrame }: ActionButtonProps) {
-    const prefix = isSelected ? "► " : "  ";
-    const displayLabel = spinnerFrame ? `${spinnerFrame} ${label}...` : `[ ${label} ]`;
-    
-    if (isSelected) {
-        return (
-            <box marginTop={1}>
-                <text fg="#000000" bg={Theme.actionButton}>
-                    {prefix}{displayLabel}
-                </text>
-            </box>
-        );
-    }
-
-    return (
-        <box marginTop={1}>
-            <text fg={Theme.actionButton}>
-                {prefix}{displayLabel}
-            </text>
-        </box>
-    );
-}

package/src/tui/components/CommandSelector.tsx

@@ -1,6 +1,9 @@
-import { Theme } from "../theme.ts";
-import { useKeyboardHandler, KeyboardPriority } from "../hooks/useKeyboardHandler.ts";
+import { useActiveKeyHandler } from "../hooks/useActiveKeyHandler.ts";
 import type { Command } from "../../core/command.ts";
+import { MenuItem } from "../semantic/MenuItem.tsx";
+import { Container } from "../semantic/Container.tsx";
+import { Panel } from "../semantic/Panel.tsx";
+import { Label } from "../semantic/Label.tsx";
 
 interface CommandItem {
     /** The command object */
@@ -20,8 +23,6 @@ interface CommandSelectorProps {
     onSelectionChange: (index: number) => void;
     /** Called when a command is selected */
     onSelect: (command: Command) => void;
-    /** Called when user wants to exit */
-    onExit: () => void;
     /** Breadcrumb path for nested commands */
     breadcrumb?: string[];
 }
@@ -34,126 +35,85 @@ export function CommandSelector({
     selectedIndex,
     onSelectionChange,
     onSelect,
-    onExit,
     breadcrumb,
 }: CommandSelectorProps) {
-    // Keyboard handler for navigation
-    useKeyboardHandler(
-        (event) => {
-            const { key } = event;
+    // Active keyboard handler for navigation
+    useActiveKeyHandler((key) => {
+        // Arrow key navigation
+        if (key.name === "down") {
+            const newIndex = Math.min(selectedIndex + 1, commands.length - 1);
+            onSelectionChange(newIndex);
+            return true;
+        }
 
-            // Arrow key navigation
-            if (key.name === "down") {
-                const newIndex = Math.min(selectedIndex + 1, commands.length - 1);
-                onSelectionChange(newIndex);
-                event.stopPropagation();
-                return;
-            }
-
-            if (key.name === "up") {
-                const newIndex = Math.max(selectedIndex - 1, 0);
-                onSelectionChange(newIndex);
-                event.stopPropagation();
-                return;
-            }
+        if (key.name === "up") {
+            const newIndex = Math.max(selectedIndex - 1, 0);
+            onSelectionChange(newIndex);
+            return true;
+        }
 
-            // Enter to select command
-            if (key.name === "return" || key.name === "enter") {
-                const selected = commands[selectedIndex];
-                if (selected) {
-                    onSelect(selected.command);
-                }
-                event.stopPropagation();
-                return;
+        // Enter to select command
+        if (key.name === "return" || key.name === "enter") {
+            const selected = commands[selectedIndex];
+            if (selected) {
+                onSelect(selected.command);
             }
+            return true;
+        }
 
-            // Escape to exit or go back
-            if (key.name === "escape") {
-                onExit();
-                event.stopPropagation();
-                return;
-            }
-        },
-        KeyboardPriority.Focused
-    );
+        return false;
+    });
 
     const title = breadcrumb?.length 
         ? `Select Command (${breadcrumb.join(" › ")})`
         : "Select Command";
 
     return (
-        <box
-            flexDirection="column"
-            flexGrow={1}
-            justifyContent="center"
-            alignItems="center"
-            gap={1}
-        >
-            <box
+        <Container flexDirection="column" flex={1} justifyContent="center" alignItems="center" gap={1}>
+            <Panel
                 flexDirection="column"
-                border={true}
-                borderStyle="rounded"
-                borderColor={Theme.borderFocused}
                 title={title}
-                paddingLeft={3}
-                paddingRight={3}
-                paddingTop={1}
-                paddingBottom={1}
-                minWidth={60}
+                padding={undefined}
+                width={60}
+                focused
             >
-                <box flexDirection="column" gap={1}>
+                <Container flexDirection="column" gap={1}>
                     {commands.map((item, idx) => {
                         const isSelected = idx === selectedIndex;
-                        const prefix = isSelected ? "► " : "  ";
                         const label = item.label ?? item.command.displayName ?? item.command.name;
                         const description = item.description ?? item.command.description;
 
-                        // Show mode indicators
                         const modeIndicator = getModeIndicator(item.command);
 
-                        if (isSelected) {
-                            return (
-                                <box key={item.command.name} flexDirection="column">
-                                    <text fg="#000000" bg="cyan">
-                                        {prefix}{label} {modeIndicator}
-                                    </text>
-                                    <text fg={Theme.label}>
-                                        {"    "}{description}
-                                    </text>
-                                </box>
-                            );
-                        }
-
                         return (
-                            <box key={item.command.name} flexDirection="column">
-                                <text fg={Theme.value}>
-                                    {prefix}{label} {modeIndicator}
-                                </text>
-                                <text fg={Theme.border}>
-                                    {"    "}{description}
-                                </text>
-                            </box>
+                            <MenuItem
+                                key={item.command.name}
+                                label={label}
+                                description={description}
+                                suffix={modeIndicator}
+                                selected={isSelected}
+                                onActivate={() => onSelect(item.command)}
+                            />
                         );
                     })}
-                </box>
-            </box>
+                </Container>
+            </Panel>
 
-            <text fg={Theme.label}>
-                ↑↓ Navigate • Enter Select • Esc {breadcrumb?.length ? "Back" : "Exit"}
-            </text>
-        </box>
+            <Label color="mutedText">↑/↓ Navigate • Enter Select • Esc {breadcrumb?.length ? "Back" : "Exit"}</Label>
+        </Container>
     );
 }
 
 /**
- * Get mode indicator for a command (e.g., "[cli]", "[tui]", "[cli/tui]").
+ * Get mode indicator for a command (e.g., "[cli]", "[tui]", "→" for subcommands).
  */
 function getModeIndicator(command: Command): string {
-    const cli = command.supportsCli();
-    const tui = command.supportsTui();
+    // Show navigation indicator for container commands with navigable subcommands
+    // (excluding commands that don't support TUI)
+    const navigableSubCommands = command.subCommands?.filter((sub) => sub.supportsTui()) ?? [];
+    if (navigableSubCommands.length > 0) {
+        return "→";
+    }
     
-    if (cli && tui) return "";
-    if (cli) return "[cli]";
-    if (tui) return "[tui]";
     return "";
 }

package/src/tui/components/ConfigForm.tsx

@@ -1,8 +1,11 @@
 import { useRef, useEffect, type ReactNode } from "react";
-import type { ScrollBoxRenderable } from "@opentui/core";
-import { Theme } from "../theme.ts";
-import { FieldRow } from "./FieldRow.tsx";
-import { useKeyboardHandler, KeyboardPriority } from "../hooks/useKeyboardHandler.ts";
+import { Field } from "../semantic/Field.tsx";
+import { MenuButton } from "../semantic/MenuButton.tsx";
+import { Panel } from "../semantic/Panel.tsx";
+import { ScrollView, type ScrollViewRef } from "../semantic/ScrollView.tsx";
+import { Container } from "../semantic/Container.tsx";
+import { useActiveKeyHandler } from "../hooks/useActiveKeyHandler.ts";
+import type { KeyboardEvent } from "../adapters/types.ts";
 import type { FieldConfig } from "./types.ts";
 
 interface ConfigFormProps {
@@ -26,6 +29,10 @@ interface ConfigFormProps {
     getDisplayValue?: (key: string, value: unknown, type: string) => string;
     /** The action button component */
     actionButton: ReactNode;
+    /** Optional additional buttons rendered before the main action button */
+    additionalButtons?: { label: string; onPress: () => void }[];
+    /** Optional handler for additional keys (called before default handling) */
+    onKeyDown?: (event: KeyboardEvent) => boolean;
 }
 
 /**
@@ -56,72 +63,80 @@ export function ConfigForm({
     onAction,
     getDisplayValue = defaultGetDisplayValue,
     actionButton,
+    additionalButtons = [],
+    onKeyDown,
 }: ConfigFormProps) {
-    const borderColor = focused ? Theme.borderFocused : Theme.border;
-    const scrollboxRef = useRef<ScrollBoxRenderable>(null);
-    const totalFields = fieldConfigs.length + 1; // +1 for action button
+    const scrollViewRef = useRef<ScrollViewRef | null>(null);
+    const totalItems = fieldConfigs.length + additionalButtons.length + 1; // fields + additional buttons + action button
 
     // Auto-scroll to keep selected item visible
     useEffect(() => {
-        if (scrollboxRef.current) {
-            scrollboxRef.current.scrollTo(selectedIndex);
-        }
+        scrollViewRef.current?.scrollToIndex(selectedIndex);
     }, [selectedIndex]);
 
-    // Handle keyboard events at Focused priority (only when focused)
-    useKeyboardHandler(
-        (event) => {
-            const { key } = event;
+    // Handle keyboard events (only when focused)
+    useActiveKeyHandler(
+        (event: KeyboardEvent) => {
+            // Let parent handle first if provided
+            if (onKeyDown?.(event)) {
+                return true;
+            }
+
+            const key = event;
 
             // Arrow key navigation
             if (key.name === "down") {
-                const newIndex = Math.min(selectedIndex + 1, totalFields - 1);
+                const newIndex = Math.min(selectedIndex + 1, totalItems - 1);
                 onSelectionChange(newIndex);
-                event.stopPropagation();
-                return;
+                return true;
             }
 
             if (key.name === "up") {
                 const newIndex = Math.max(selectedIndex - 1, 0);
                 onSelectionChange(newIndex);
-                event.stopPropagation();
-                return;
+                return true;
             }
 
-            // Enter to edit field or run action
+            // Enter to edit field, press additional button, or run action
             if (key.name === "return" || key.name === "enter") {
-                if (selectedIndex === fieldConfigs.length) {
-                    onAction();
-                } else {
+                if (selectedIndex < fieldConfigs.length) {
+                    // It's a field
                     const fieldConfig = fieldConfigs[selectedIndex];
                     if (fieldConfig) {
                         onEditField(fieldConfig.key);
                     }
+                } else if (selectedIndex < fieldConfigs.length + additionalButtons.length) {
+                    // It's an additional button
+                    const buttonIndex = selectedIndex - fieldConfigs.length;
+                    additionalButtons[buttonIndex]?.onPress();
+                } else {
+                    // It's the main action button
+                    onAction();
                 }
-                event.stopPropagation();
-                return;
+                return true;
             }
+
+            return false;
         },
-        KeyboardPriority.Focused,
         { enabled: focused }
     );
 
     return (
-        <box
-            flexDirection="column"
-            border={true}
-            borderStyle="rounded"
-            borderColor={borderColor}
+        <Panel
             title={title}
-            flexGrow={1}
+            focused={focused}
+            flex={1}
             padding={1}
+            flexDirection="column"
         >
-            <scrollbox
-                ref={scrollboxRef}
-                scrollY={true}
-                flexGrow={1}
+            <ScrollView
+                axis="vertical"
+                flex={1}
+                scrollRef={(ref) => {
+                    scrollViewRef.current = ref;
+                }}
             >
-                <box flexDirection="column" gap={0}>
+                <Container flexDirection="column" gap={0}>
                     {fieldConfigs.map((field, idx) => {
                         const isSelected = idx === selectedIndex;
                         const displayValue = getDisplayValue(
@@ -131,18 +146,29 @@ export function ConfigForm({
                         );
 
                         return (
-                            <FieldRow
+                            <Field
                                 key={field.key}
                                 label={field.label}
                                 value={displayValue}
-                                isSelected={isSelected}
+                                selected={isSelected}
+                            />
+                        );
+                    })}
+
+                    {additionalButtons.map((btn, idx) => {
+                        const buttonSelectedIndex = fieldConfigs.length + idx;
+                        return (
+                            <MenuButton
+                                key={btn.label}
+                                label={btn.label}
+                                selected={selectedIndex === buttonSelectedIndex}
                             />
                         );
                     })}
 
                     {actionButton}
-                </box>
-            </scrollbox>
-        </box>
+                </Container>
+            </ScrollView>
+        </Panel>
     );
 }

package/src/tui/components/FieldRow.tsx

@@ -1,30 +0,0 @@
-import { Theme } from "../theme.ts";
-
-interface FieldRowProps {
-    /** Field label */
-    label: string;
-    /** Field value to display */
-    value: string;
-    /** Whether this row is selected */
-    isSelected: boolean;
-}
-
-/**
- * A single row in a config form displaying a field label and value.
- */
-export function FieldRow({ label, value, isSelected }: FieldRowProps) {
-    const prefix = isSelected ? "► " : "  ";
-    const labelColor = isSelected ? Theme.borderFocused : Theme.label;
-    const valueColor = isSelected ? Theme.value : Theme.statusText;
-
-    return (
-        <box flexDirection="row" gap={1}>
-            <text fg={labelColor}>
-                {prefix}{label}:
-            </text>
-            <text fg={valueColor}>
-                {value}
-            </text>
-        </box>
-    );
-}

package/src/tui/components/Header.tsx

@@ -1,4 +1,6 @@
-import { Theme } from "../theme.ts";
+import { Container } from "../semantic/Container.tsx";
+import { Label } from "../semantic/Label.tsx";
+import { Spacer } from "../semantic/Spacer.tsx";
 
 interface HeaderProps {
     /** Application name */
@@ -13,19 +15,18 @@ interface HeaderProps {
  * Application header with name, version, and optional breadcrumb.
  */
 export function Header({ name, version, breadcrumb }: HeaderProps) {
-    const breadcrumbStr = breadcrumb?.length 
-        ? ` › ${breadcrumb.join(" › ")}`
-        : "";
+    const breadcrumbStr = breadcrumb?.length ? ` › ${breadcrumb.join(" › ")}` : "";
 
     return (
-        <box flexDirection="row" justifyContent="space-between" marginBottom={1}>
-            <text fg={Theme.header}>
-                <strong>{name}</strong>
-                {breadcrumbStr}
-            </text>
-            <text fg={Theme.label}>
-                v{version}
-            </text>
-        </box>
+        <Container flexDirection="column" noShrink>
+            <Container flexDirection="row" justifyContent="space-between">
+                <Label color="mutedText" bold>
+                    {name}
+                    {breadcrumbStr}
+                </Label>
+                <Label color="mutedText">v{version}</Label>
+            </Container>
+            <Spacer size={1} />
+        </Container>
     );
 }

package/src/tui/components/JsonHighlight.tsx

@@ -1,20 +1,14 @@
-import { Theme } from "../theme.ts";
+import { Container } from "../semantic/Container.tsx";
+import { CodeHighlight } from "../semantic/CodeHighlight.tsx";
+import type { CodeTokenType } from "../semantic/types.ts";
 
 /**
  * JSON syntax highlighting types and colors
  */
-type JsonTokenType = "key" | "string" | "number" | "boolean" | "null" | "punctuation";
+type JsonTokenType = Exclude<CodeTokenType, "unknown">;
 type JsonToken = { type: JsonTokenType; value: string };
 type JsonLineTokens = JsonToken[];
 
-const TOKEN_COLORS: Record<JsonTokenType, string> = {
-    key: "#61afef",      // blue
-    string: "#98c379",   // green
-    number: "#d19a66",   // orange
-    boolean: "#c678dd",  // purple
-    null: "#c678dd",     // purple
-    punctuation: Theme.label,
-};
 
 function tokenizeJson(value: unknown, indent = 0): JsonLineTokens[] {
     const pad = "  ".repeat(indent);
@@ -115,14 +109,13 @@ export interface JsonHighlightProps {
 export function JsonHighlight({ value }: JsonHighlightProps) {
     const lines = tokenizeJson(value);
     return (
-        <box flexDirection="column">
+        <Container flexDirection="column" gap={0}>
             {lines.map((tokens, lineIdx) => (
-                <text key={`json-${lineIdx}`}>
-                    {tokens.map((token, tokenIdx) => (
-                        <span key={tokenIdx} fg={TOKEN_COLORS[token.type]}>{token.value}</span>
-                    ))}
-                </text>
+                <CodeHighlight
+                    key={`json-${lineIdx}`}
+                    tokens={tokens.map((token) => ({ type: token.type, value: token.value }))}
+                />
             ))}
-        </box>
+        </Container>
     );
 }