@pablozaiden/terminatui 0.2.0 → 0.3.0

package/src/tui/registry.ts

@@ -0,0 +1,102 @@
+import type { ReactNode } from "react";
+import { CliModal } from "./modals/CliModal.tsx";
+import { EditorModal } from "./modals/EditorModal.tsx";
+import { LogsModal } from "./modals/LogsModal.tsx";
+import type { ScreenBase } from "./screens/ScreenBase";
+import { CommandSelectScreen } from "./screens/CommandSelectScreen";
+import { ConfigScreen } from "./screens/ConfigScreen";
+import { ErrorScreen } from "./screens/ErrorScreen";
+import { ResultsScreen } from "./screens/ResultsScreen";
+import { RunningScreen } from "./screens/RunningScreen";
+
+/**
+ * Screen component type.
+ * Screens receive no props - they get everything from context.
+ */
+export type ScreenComponent = () => ReactNode;
+
+/**
+ * Modal component type.
+ * Modals receive their params and a close function.
+ */
+export type ModalComponent<TParams> = (props: {
+    params: TParams;
+    onClose: () => void;
+}) => ReactNode;
+
+
+/**
+ * Screen registry - maps route names to screen components.
+ */
+const screenRegistry = new Map<string, ScreenComponent>();
+
+/**
+ * Modal registry - maps modal IDs to modal components.
+ */
+const modalRegistry = new Map<string, ModalComponent<any>>();
+
+/**
+ * Register a screen component for a route.
+ * Typically called at module load time.
+ */
+
+export function registerScreen(screen: ScreenBase): void {
+    screenRegistry.set(screen.getRoute(), screen.component());
+}
+
+/**
+ * Register a modal component for a modal ID.
+ * Typically called at module load time.
+ */
+export interface ModalDefinition<TParams> {
+    getId(): string;
+    component(): ModalComponent<TParams>;
+}
+
+export function registerModal<TParams>(modal: ModalDefinition<TParams>): void {
+    modalRegistry.set(modal.getId(), modal.component());
+}
+
+/**
+ * Get a screen component by route.
+ * Returns undefined if not registered.
+ */
+export function getScreen(route: string): ScreenComponent | undefined {
+    return screenRegistry.get(route);
+}
+
+/**
+ * Get a modal component by ID.
+ * Returns undefined if not registered.
+ */
+export function getModal<TParams>(id: string): ModalComponent<TParams> | undefined {
+    return modalRegistry.get(id);
+}
+
+/**
+ * Get all registered screen routes.
+ */
+export function getRegisteredScreens(): string[] {
+    return Array.from(screenRegistry.keys());
+}
+
+/**
+ * Get all registered modal IDs.
+ */
+export function getRegisteredModals(): string[] {
+    return Array.from(modalRegistry.keys());
+}
+
+export function registerAllScreens(): void {
+    registerScreen(new CommandSelectScreen());
+    registerScreen(new ConfigScreen());
+    registerScreen(new RunningScreen());
+    registerScreen(new ResultsScreen());
+    registerScreen(new ErrorScreen());
+}
+
+export function registerAllModals(): void {
+    registerModal(new EditorModal());
+    registerModal(new CliModal());
+    registerModal(new LogsModal());
+}

package/src/tui/screens/CommandSelectScreen.tsx

@@ -0,0 +1,162 @@
+import { useState, useMemo, useCallback } from "react";
+import type { AnyCommand } from "../../core/command.ts";
+import { CommandSelector } from "../components/CommandSelector.tsx";
+import { useTuiApp } from "../context/TuiAppContext.tsx";
+import { useNavigation } from "../context/NavigationContext.tsx";
+import { useBackHandler } from "../hooks/useBackHandler.ts";
+import type { ScreenComponent } from "../registry.ts";
+import { loadPersistedParameters } from "../utils/parameterPersistence.ts";
+import { schemaToFieldConfigs } from "../utils/schemaToFields.ts";
+import type { OptionDef, OptionSchema } from "../../types/command.ts";
+import { ScreenBase } from "./ScreenBase.ts";
+import { type ConfigParams, ConfigScreen } from "./ConfigScreen.tsx";
+
+/**
+ * Screen state stored in navigation params.
+ */
+export interface CommandSelectParams {
+    commandPath: string[];
+}
+
+/**
+ * Command selection screen.
+ * Fully self-contained - gets all data from context and handles its own transitions.
+ */
+export class CommandSelectScreen extends ScreenBase {
+    static readonly Id = "command-select";
+
+    getRoute(): string {
+        return CommandSelectScreen.Id;
+    }
+
+    override component(): ScreenComponent {
+        return function CommandSelectScreenComponent() {
+            const { name, commands } = useTuiApp();
+            const navigation = useNavigation();
+            
+            // Get params from navigation, with defaults
+            const params = (navigation.current.params ?? { commandPath: [] }) as CommandSelectParams;
+            const commandPath = params.commandPath ?? [];
+            
+            // Local selection state
+            const [selectedIndex, setSelectedIndex] = useState(0);
+
+            // Get current commands based on path
+            const currentCommands = useMemo<AnyCommand[]>(() => {
+                if (commandPath.length === 0) {
+                    return commands.filter((cmd) => cmd.supportsTui());
+                }
+
+                let current: AnyCommand[] = commands;
+                for (const pathPart of commandPath) {
+                    const found = current.find((c) => c.name === pathPart);
+                    if (found?.subCommands) {
+                        current = found.subCommands.filter((sub) => sub.supportsTui());
+                    } else {
+                        break;
+                    }
+                }
+                return current;
+            }, [commands, commandPath]);
+
+            // Build breadcrumb from path
+            const breadcrumb = useMemo(() => {
+                if (commandPath.length === 0) return undefined;
+
+                const displayNames: string[] = [];
+                let current: AnyCommand[] = commands;
+
+                for (const pathPart of commandPath) {
+                    const found = current.find((c) => c.name === pathPart);
+                    if (found) {
+                        displayNames.push(found.displayName ?? found.name);
+                        if (found.subCommands) {
+                            current = found.subCommands;
+                        }
+                    } else {
+                        displayNames.push(pathPart);
+                    }
+                }
+
+                return displayNames;
+            }, [commandPath, commands]);
+
+            const items = currentCommands.map((cmd) => ({
+                command: cmd,
+                label: cmd.displayName ?? cmd.name,
+                description: cmd.description,
+            }));
+
+            // Handle command selection - this screen decides where to go next
+            const handleSelect = useCallback((cmd: AnyCommand) => {
+                // If command has runnable subcommands, navigate deeper
+                if (cmd.subCommands && cmd.subCommands.some((c) => c.supportsTui())) {
+                    navigation.replace<CommandSelectParams>(CommandSelectScreen.Id, { commandPath: [...commandPath, cmd.name] });
+                    return;
+                }
+
+                // Otherwise, push to config screen
+                navigation.push<ConfigParams>(ConfigScreen.Id, {
+                    command: cmd,
+                    commandPath: [...commandPath, cmd.name],
+                    values: initializeConfigValues(name, cmd),
+                    fieldConfigs: schemaToFieldConfigs(cmd.options),
+                });
+            }, [navigation, commandPath, name]);
+
+            // Register back handler - this screen decides what back means
+            useBackHandler(useCallback(() => {
+                if (commandPath.length > 0) {
+                    // Go up one level
+                    navigation.replace<CommandSelectParams>(CommandSelectScreen.Id, { commandPath: commandPath.slice(0, -1) });
+                    return true; // We handled it
+                }
+                // At root - let navigation call onExit
+                return false;
+            }, [navigation, commandPath]));
+
+            return (
+                <CommandSelector
+                    commands={items}
+                    selectedIndex={selectedIndex}
+                    onSelectionChange={setSelectedIndex}
+                    onSelect={handleSelect}
+                    breadcrumb={breadcrumb}
+                />
+            );
+        };
+    }
+}
+
+/**
+ * Initialize config values from defaults and persisted values.
+ */
+function initializeConfigValues(appName: string, cmd: AnyCommand): Record<string, unknown> {
+    const defaults: Record<string, unknown> = {};
+    const optionDefs = cmd.options as OptionSchema;
+    
+    for (const [key, def] of Object.entries(optionDefs)) {
+        const typedDef = def as OptionDef;
+        if (typedDef.default !== undefined) {
+            defaults[key] = typedDef.default;
+        } else {
+            switch (typedDef.type) {
+                case "string":
+                    defaults[key] = typedDef.enum?.[0] ?? "";
+                    break;
+                case "number":
+                    defaults[key] = typedDef.min ?? 0;
+                    break;
+                case "boolean":
+                    defaults[key] = false;
+                    break;
+                case "array":
+                    defaults[key] = [];
+                    break;
+            }
+        }
+    }
+
+    const persisted = loadPersistedParameters(appName, cmd.name);
+    return { ...defaults, ...persisted };
+}

package/src/tui/screens/ConfigScreen.tsx

@@ -0,0 +1,165 @@
+import { useCallback, useMemo, useState } from "react";
+import type { AnyCommand } from "../../core/command.ts";
+import type { FieldConfig } from "../components/types.ts";
+import { ConfigForm } from "../components/ConfigForm.tsx";
+import { Container } from "../semantic/Container.tsx";
+import { MenuButton } from "../semantic/MenuButton.tsx";
+import { schemaToFieldConfigs } from "../utils/schemaToFields.ts";
+import { useClipboardProvider } from "../hooks/useClipboardProvider.ts";
+import { buildCliCommand } from "../utils/buildCliCommand.ts";
+import { useTuiApp } from "../context/TuiAppContext.tsx";
+import { useNavigation } from "../context/NavigationContext.tsx";
+import { useExecutor } from "../context/ExecutorContext.tsx";
+import type { ScreenComponent } from "../registry.ts";
+import { savePersistedParameters } from "../utils/parameterPersistence.ts";
+import type { OptionSchema, OptionValues } from "../../types/command.ts";
+import { ScreenBase } from "./ScreenBase.ts";
+import type { EditorModalParams } from "../modals/EditorModal.tsx";
+import type { CliModalParams } from "../modals/CliModal.tsx";
+import { RunningScreen, type RunningParams } from "./RunningScreen.tsx";
+import { type ErrorParams, ErrorScreen } from "./ErrorScreen.tsx";
+import { type ResultsParams, ResultsScreen } from "./ResultsScreen.tsx";
+
+/**
+ * Screen state stored in navigation params.
+ */
+export interface ConfigParams {
+    command: AnyCommand;
+    commandPath: string[];
+    values: Record<string, unknown>;
+    fieldConfigs: FieldConfig[];
+}
+
+/**
+ * Config screen for editing command options before execution.
+ * Fully self-contained - gets all data from context and handles its own transitions.
+ */
+export class ConfigScreen extends ScreenBase {
+    static readonly Id = "config";
+    getRoute(): string {
+        return ConfigScreen.Id;
+    }
+
+    override component(): ScreenComponent {
+        return function ConfigScreenComponent() {
+            const { name: appName } = useTuiApp();
+            const navigation = useNavigation();
+            const executor = useExecutor();
+            
+            // Get params from navigation
+            const params = navigation.current.params as ConfigParams | undefined;
+            if (!params) return null;
+            
+            const { command, commandPath, values, fieldConfigs } = params;
+            
+            // Local selection state for the form
+            const [selectedFieldIndex, setSelectedFieldIndex] = useState(0);
+
+            // Derive field configs (in case they weren't passed)
+            const derivedFieldConfigs = useMemo(
+                () => fieldConfigs ?? schemaToFieldConfigs(command.options),
+                [fieldConfigs, command.options]
+            );
+
+            // Register clipboard provider for this screen
+            useClipboardProvider(
+                useCallback(() => ({
+                    content: JSON.stringify(values, null, 2),
+                    label: "Config",
+                }), [values])
+            );
+
+            // Handle running the command
+            const handleRun = useCallback(async () => {
+                // Save parameters for next time
+                savePersistedParameters(appName, command.name, values);
+                
+                // Push to running screen
+                navigation.push<RunningParams>(RunningScreen.Id, {
+                    command,
+                    commandPath,
+                    values,
+                });
+                
+                // Execute the command
+                const outcome = await executor.execute(command, values);
+                
+                if (outcome.cancelled) {
+                    // If cancelled, pop back to config
+                    navigation.pop();
+                    return;
+                }
+                
+                if (outcome.success) {
+                    // Replace running with results
+                    navigation.replace<ResultsParams>(ResultsScreen.Id, {
+                        command,
+                        commandPath,
+                        values,
+                        result: outcome.result ?? null,
+                    });
+                } else {
+                    // Replace running with error
+                    navigation.replace<ErrorParams>(ErrorScreen.Id, {
+                        command,
+                        commandPath,
+                        values,
+                        error: outcome.error ?? new Error("Unknown error"),
+                    });
+                }
+            }, [appName, command, commandPath, values, navigation, executor]);
+
+            // Handle editing a field - open property editor modal
+            const handleEditField = useCallback((fieldKey: string) => {
+                navigation.openModal<EditorModalParams>("property-editor", {
+                    fieldKey,
+                    currentValue: values[fieldKey],
+                    fieldConfigs: derivedFieldConfigs,
+                    onSubmit: (value: unknown) => {
+                        let nextValues = { ...values, [fieldKey]: value };
+                        const updates = command.onConfigChange?.(fieldKey, value, nextValues);
+                        if (updates) {
+                            nextValues = { ...nextValues, ...updates };
+                        }
+
+                        navigation.replace<ConfigParams>(ConfigScreen.Id, { ...params, values: nextValues });
+                        navigation.closeModal();
+                    },
+                    onCancel: () => navigation.closeModal(),
+                });
+            }, [navigation, values, derivedFieldConfigs, params]);
+
+            // Handle opening the CLI Args modal
+            const handleShowCliArgs = useCallback(() => {
+                const cli = buildCliCommand(appName, commandPath, command.options, values as OptionValues<OptionSchema>);
+                navigation.openModal<CliModalParams>("cli", { command: cli });
+            }, [appName, commandPath, command.options, values, navigation]);
+
+            return (
+                <Container flexDirection="column" flex={1}>
+                    <ConfigForm
+                        title={`Configure: ${command.displayName ?? command.name}`}
+                        fieldConfigs={derivedFieldConfigs}
+                        values={values}
+                        selectedIndex={selectedFieldIndex}
+                        focused={true}
+                        onSelectionChange={setSelectedFieldIndex}
+                        onEditField={handleEditField}
+                        onAction={handleRun}
+                        additionalButtons={
+                            command.supportsCli()
+                                ? [{ label: "CLI Command", onPress: handleShowCliArgs }]
+                                : []
+                        }
+                        actionButton={
+                            <MenuButton
+                                label={command.actionLabel ?? "Run"}
+                                selected={selectedFieldIndex === derivedFieldConfigs.length + 1}
+                            />
+                        }
+                    />
+                </Container>
+            );
+        };
+    }
+}

package/src/tui/screens/ErrorScreen.tsx

@@ -0,0 +1,58 @@
+import { useCallback } from "react";
+import type { AnyCommand } from "../../core/command.ts";
+import { useNavigation } from "../context/NavigationContext.tsx";
+import { ResultsPanel } from "../components/ResultsPanel.tsx";
+import { useClipboardProvider } from "../hooks/useClipboardProvider.ts";
+import type { ScreenComponent } from "../registry.ts";
+import { ScreenBase } from "./ScreenBase.ts";
+
+/**
+ * Screen state stored in navigation params.
+ */
+export interface ErrorParams {
+    command: AnyCommand;
+    commandPath: string[];
+    values: Record<string, unknown>;
+    error: Error;
+}
+
+/**
+ * Error screen - shows command execution errors.
+ * Fully self-contained - gets all data from context and handles its own transitions.
+ */
+export class ErrorScreen extends ScreenBase {
+    static readonly Id = "error";
+
+    getRoute(): string {
+        return ErrorScreen.Id;
+    }
+
+    override component(): ScreenComponent {
+        return function ErrorScreenComponent() {
+            const navigation = useNavigation();
+            
+            // Get params from navigation
+            const params = navigation.current.params as ErrorParams | undefined;
+            if (!params) return null;
+            
+            const { error, command } = params;
+
+            // Register clipboard provider for this screen
+            useClipboardProvider(
+                useCallback(() => ({
+                    content: error.message,
+                    label: "Error",
+                }), [error])
+            );
+
+            return (
+                <ResultsPanel
+                    result={null}
+                    error={error}
+                    focused={true}
+                    renderResult={command.renderResult}
+                />
+            );
+        };
+    }
+}

package/src/tui/screens/ResultsScreen.tsx

@@ -0,0 +1,68 @@
+import { useCallback } from "react";
+import type { AnyCommand, CommandResult } from "../../core/command.ts";
+import { useNavigation } from "../context/NavigationContext.tsx";
+import { ResultsPanel } from "../components/ResultsPanel.tsx";
+import { useClipboardProvider } from "../hooks/useClipboardProvider.ts";
+import { type ScreenComponent } from "../registry.ts";
+import { ScreenBase } from "./ScreenBase.ts";
+import { useRenderer } from "../context/RendererContext.tsx";
+
+/**
+ * Screen state stored in navigation params.
+ */
+export interface ResultsParams {
+    command: AnyCommand;
+    commandPath: string[];
+    values: Record<string, unknown>;
+    result: unknown;
+}
+
+export class ResultsScreen extends ScreenBase {
+    static readonly Id = "results";
+
+    getRoute(): string {
+        return ResultsScreen.Id;
+    }
+    /**
+     * Results screen - shows command execution results.
+     * Fully self-contained - gets all data from context and handles its own transitions.
+     */
+    override component(): ScreenComponent {
+        return function ResultsScreenComponent() {
+            const navigation = useNavigation();
+
+            // Get params from navigation
+            const params = navigation.current.params as ResultsParams | undefined;
+            if (!params) return null;
+
+            const { result, command } = params;
+
+            const renderer = useRenderer();
+
+            let renderFunction = undefined;
+            if (renderer.supportCustomRendering()) {
+                renderFunction = command.renderResult;
+            }
+
+            // Register clipboard provider for this screen
+            useClipboardProvider(
+                useCallback(() => {
+                    if (command.getClipboardContent) {
+                        const custom = command.getClipboardContent(result as CommandResult);
+                        if (custom) return { content: custom, label: "Results" };
+                    }
+                    return { content: JSON.stringify(result, null, 2), label: "Results" };
+                }, [result, command])
+            );
+
+            return (
+                <ResultsPanel
+                    result={result as CommandResult | null}
+                    error={null}
+                    focused={true}
+                    renderResult={renderFunction}
+                />
+            );
+        }
+    }
+}

package/src/tui/screens/RunningScreen.tsx

@@ -0,0 +1,72 @@
+import { useCallback } from "react";
+import type { AnyCommand } from "../../core/command.ts";
+import { useNavigation } from "../context/NavigationContext.tsx";
+import { useExecutor } from "../context/ExecutorContext.tsx";
+import { useBackHandler } from "../hooks/useBackHandler.ts";
+import type { ScreenComponent } from "../registry.ts";
+import { ScreenBase } from "./ScreenBase.ts";
+import { Container } from "../semantic/Container.tsx";
+import { Label } from "../semantic/Label.tsx";
+import { Panel } from "../semantic/Panel.tsx";
+
+/**
+ * Screen state stored in navigation params.
+ */
+export interface RunningParams {
+    command: AnyCommand;
+    commandPath: string[];
+    values: Record<string, unknown>;
+}
+
+/**
+ * Running screen - shows while a command is executing.
+ * Fully self-contained - gets all data from context and handles its own transitions.
+ */
+export class RunningScreen extends ScreenBase {
+    static readonly Id = "running";
+    getRoute(): string {
+        return RunningScreen.Id;
+    }
+
+    override component(): ScreenComponent {
+        return function RunningScreenComponent() {
+            const navigation = useNavigation();
+            const executor = useExecutor();
+            
+            // Get params from navigation
+            const params = navigation.current.params as RunningParams | undefined;
+            if (!params) return null;
+            
+            const { command } = params;
+
+            // Register back handler - cancel execution on back
+            useBackHandler(useCallback(() => {
+                if (executor.isExecuting) {
+                    executor.cancel();
+                    executor.reset();
+                    // Pop back to config screen
+                    navigation.pop();
+                    return true;
+                }
+                return false;
+            }, [executor, navigation]));
+
+            return (
+                <Panel
+                    flexDirection="column"
+                    flex={1}
+                    title={`${command.displayName ?? command.name}`}
+                    padding={1}
+                    focused
+                >
+                    <Container flexDirection="column" flex={1} gap={1}>
+                        <Label color="mutedText">
+                            Check logs for progress.
+                        </Label>
+                        <Label color="mutedText">Press Esc to cancel.</Label>
+                    </Container>
+                </Panel>
+            );
+        };
+    }
+}

package/src/tui/screens/ScreenBase.ts

@@ -0,0 +1,6 @@
+import type { ScreenComponent } from "../registry";
+
+export abstract class ScreenBase {
+    abstract component(): ScreenComponent;
+    abstract getRoute(): string;
+}

package/src/tui/semantic/Button.tsx

@@ -0,0 +1,7 @@
+import type { ButtonProps } from "./types.ts";
+import { useRenderer } from "../context/RendererContext.tsx";
+
+export function Button(props: ButtonProps) {
+    const renderer = useRenderer();
+    return renderer.components.Button(props);
+}

package/src/tui/semantic/Code.tsx

@@ -0,0 +1,7 @@
+import type { CodeProps } from "./types.ts";
+import { useRenderer } from "../context/RendererContext.tsx";
+
+export function Code(props: CodeProps) {
+    const renderer = useRenderer();
+    return renderer.components.Code(props);
+}

package/src/tui/semantic/CodeHighlight.tsx

@@ -0,0 +1,7 @@
+import type { CodeHighlightProps } from "./types.ts";
+import { useRenderer } from "../context/RendererContext.tsx";
+
+export function CodeHighlight(props: CodeHighlightProps) {
+    const renderer = useRenderer();
+    return renderer.components.CodeHighlight(props);
+}

package/src/tui/semantic/Container.tsx

@@ -0,0 +1,7 @@
+import type { ContainerProps } from "./types.ts";
+import { useRenderer } from "../context/RendererContext.tsx";
+
+export function Container(props: ContainerProps) {
+    const renderer = useRenderer();
+    return renderer.components.Container(props);
+}

package/src/tui/semantic/Field.tsx

@@ -0,0 +1,7 @@
+import type { FieldProps } from "./types.ts";
+import { useRenderer } from "../context/RendererContext.tsx";
+
+export function Field(props: FieldProps) {
+    const renderer = useRenderer();
+    return renderer.components.Field(props);
+}