@pablozaiden/terminatui 0.3.0-beta-1 → 0.4.0

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "@pablozaiden/terminatui",
-  "version": "0.3.0-beta-1",
+  "version": "0.4.0",
   "description": "Terminal UI and Command Line Application Framework",
   "repository": {
     "url": "https://github.com/PabloZaiden/terminatui"
   },
   "type": "module",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "files": [
+    "src/**/*"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
   "scripts": {
     "build": "bunx tsc --noEmit",
     "test": "bun test",

package/src/__tests__/adapterNoSharedUi.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from "bun:test";
+import { Glob } from "bun";
+import { fileURLToPath } from "node:url";
+
+const adaptersDir = fileURLToPath(new URL("../tui/adapters", import.meta.url));
+
+async function getAdapterSourceFiles(): Promise<string[]> {
+	const glob = new Glob("**/*.{ts,tsx}");
+	const files: string[] = [];
+	for await (const file of glob.scan({ cwd: adaptersDir, absolute: true })) {
+		// skip shared behavior (allowed)
+		if (!file.includes("/shared/")) {
+			files.push(file);
+		}
+	}
+	return files;
+}
+
+test("Adapters must not import src/tui/components/*", async () => {
+	const files = await getAdapterSourceFiles();
+	expect(files.length).toBeGreaterThan(0);
+
+	const forbidden = /from\s+['"][^'"]*tui\/components\//;
+
+	for (const filePath of files) {
+		const source = await Bun.file(filePath).text();
+		const match = source.match(forbidden);
+		if (match) {
+			throw new Error(
+				`Adapter file imports shared component:\n  File: ${filePath}\n  Match: ${match[0]}`
+			);
+		}
+	}
+});

package/src/__tests__/configOnChange.test.ts

@@ -0,0 +1,63 @@
+import { test, expect } from "bun:test";
+import { Command } from "../core/command.ts";
+import type { OptionSchema } from "../types/command.ts";
+
+class TestCommand extends Command<typeof TestCommand.Options> {
+  static readonly Options = {
+    a: { type: "string" as const, description: "a" },
+    b: { type: "string" as const, description: "b" },
+  } as const satisfies OptionSchema;
+
+  readonly name = "my";
+  readonly description = "my";
+  readonly options = TestCommand.Options;
+
+  public readonly onChangeCalls: Array<[
+    string,
+    unknown,
+    Record<string, unknown>
+  ]> = [];
+
+  override execute(): void {}
+
+  override onConfigChange(
+    key: string,
+    value: unknown,
+    allValues: Record<string, unknown>
+  ) {
+    this.onChangeCalls.push([key, value, allValues]);
+    if (key === "a") {
+      return { b: "derived" };
+    }
+    return undefined;
+  }
+
+  applyTuiConfigChange(
+    key: string,
+    value: unknown,
+    values: Record<string, unknown>
+  ): Record<string, unknown> {
+    let nextValues: Record<string, unknown> = { ...values, [key]: value };
+
+    const updates = this.onConfigChange?.(key, value, nextValues);
+    if (updates && typeof updates === "object") {
+      nextValues = { ...nextValues, ...updates };
+    }
+
+    return nextValues;
+  }
+}
+
+test("onConfigChange merges returned updates", () => {
+  const command = new TestCommand();
+
+  const next = command.applyTuiConfigChange("a", "new", {
+    a: "old",
+    b: "oldb",
+  });
+
+  expect(command.onChangeCalls.length).toBe(1);
+  expect(command.onChangeCalls[0]?.[0]).toBe("a");
+  expect(command.onChangeCalls[0]?.[1]).toBe("new");
+  expect(next).toEqual({ a: "new", b: "derived" });
+});

package/src/__tests__/schemaToFields.test.ts

@@ -21,8 +21,6 @@ describe("schemaToFields", () => {
           label: "Repository",
         },
         hidden: { type: "string", description: "Hidden", tuiHidden: true },
-        path: { type: "string", description: "Path", placeholder: "Enter path here" },
-        grouped: { type: "string", description: "Grouped", group: "Basic" },
       };
 
       const fields = schemaToFieldConfigs(schema);
@@ -42,8 +40,6 @@ describe("schemaToFields", () => {
       // Decorations
       expect(fields.find((f) => f.key === "repoPath")?.label).toBe("Repository");
       expect(fields.some((f) => f.key === "hidden")).toBe(false);
-      expect(fields.find((f) => f.key === "path")?.placeholder).toBe("Enter path here");
-      expect(fields.find((f) => f.key === "grouped")?.group).toBe("Basic");
     });
 
     test("sorts by order", () => {

package/src/__tests__/tuiRootNoCoupling.test.ts

@@ -0,0 +1,25 @@
+import { expect, test } from "bun:test";
+
+const tuiRootPath = new URL("../tui/TuiRoot.tsx", import.meta.url);
+
+async function readTuiRootSource() {
+	return await Bun.file(tuiRootPath).text();
+}
+
+test("TuiRoot stays a thin host (no domain helper imports)", async () => {
+	const source = await readTuiRootSource();
+
+	const forbiddenFragments = [
+		"buildCliCommand",
+		"schemaToFieldConfigs",
+		"schemaToFields",
+		"initializeConfigValues",
+		"loadPersistedParameters",
+		"savePersistedParameters",
+		"getCommandsAtPath",
+	];
+
+	for (const fragment of forbiddenFragments) {
+		expect(source).not.toContain(fragment);
+	}
+});

package/src/builtins/version.ts

@@ -18,7 +18,7 @@ interface VersionConfig {
  * Format version string with optional commit hash.
  * If commitHash is empty or undefined, shows "(dev)".
  */
-function formatVersion(version: string, commitHash?: string): string {
+export function formatVersion(version: string, commitHash?: string): string {
   const hashPart = commitHash && commitHash.length > 0 
     ? commitHash.substring(0, 7) 
     : "(dev)";

package/src/index.ts

@@ -0,0 +1,22 @@
+export * from "./builtins/help.ts";
+export * from "./builtins/settings.ts";
+export * from "./builtins/version.ts";
+
+export * from "./cli/parser.ts";
+export * from "./cli/output/colors.ts";
+
+export * from "./core/application.ts";
+export * from "./core/command.ts";
+export * from "./core/context.ts";
+export * from "./core/help.ts";
+export * from "./core/knownCommands.ts";
+export * from "./core/logger.ts";
+export * from "./core/registry.ts";
+
+export * from "./tui/TuiApplication.tsx";
+export * from "./tui/TuiRoot.tsx";
+export * from "./tui/theme.ts";
+export * from "./types/command.ts";
+
+// Kept for external consumers.
+export * from "./tui/components/JsonHighlight.tsx";

package/src/tui/TuiApplication.tsx

@@ -8,7 +8,6 @@ import { createSettingsCommand } from "../builtins/settings.ts";
 import { KNOWN_COMMANDS } from "../core/knownCommands.ts";
 import { loadPersistedParameters } from "./utils/parameterPersistence.ts";
 import { AppContext } from "../core/context.ts";
-import { registerAllModals, registerAllScreens } from "./registry.ts";
 
 /**
  * Extended configuration for TUI-enabled applications.
@@ -87,9 +86,6 @@ export class TuiApplication extends Application {
      * Launch the TUI.
      */
     async runTui(rendererType: TuiModeOptions): Promise<void> {
-        await registerAllScreens();
-        await registerAllModals();
-        
         // Get all commands that support TUI or have options
         const commands = this.getExecutableCommands();
 

package/src/tui/TuiRoot.tsx

@@ -1,18 +1,14 @@
 import type { AnyCommand } from "../core/command.ts";
-import { useClipboard } from "./hooks/useClipboard.ts";
-import { KeyboardProvider } from "./context/KeyboardContext.tsx";
-import { useGlobalKeyHandler } from "./hooks/useGlobalKeyHandler.ts";
+import { useState } from "react";
 import { LogsProvider } from "./context/LogsContext.tsx";
 import { NavigationProvider, useNavigation } from "./context/NavigationContext.tsx";
-import { ClipboardProviderComponent, useClipboardContext } from "./context/ClipboardContext.tsx";
 import { TuiAppContextProvider, useTuiApp } from "./context/TuiAppContext.tsx";
-import { ExecutorProvider, useExecutor } from "./context/ExecutorContext.tsx";
-import { Header } from "./components/Header.tsx";
-import { StatusBar } from "./components/StatusBar.tsx";
-import { Container } from "./semantic/Container.tsx";
-import { Panel } from "./semantic/Panel.tsx";
-import { getScreen, getModal } from "./registry.ts";
-import { CommandSelectScreen, type CommandSelectParams } from "./screens/CommandSelectScreen.tsx";
+import { ExecutorProvider } from "./context/ExecutorContext.tsx";
+import { ActionProvider, useAction } from "./context/ActionContext.tsx";
+import { useRenderer } from "./context/RendererContext.tsx";
+
+import { TuiDriverProvider, useTuiDriver } from "./driver/context/TuiDriverContext.tsx";
+
 
 interface TuiRootProps {
     name: string;
@@ -24,28 +20,26 @@ interface TuiRootProps {
 
 export function TuiRoot({ name, displayName, version, commands, onExit }: TuiRootProps) {
     return (
-        <KeyboardProvider>
-            <ClipboardProviderComponent>
-                <TuiAppContextProvider
-                    name={name}
-                    displayName={displayName}
-                    version={version}
-                    commands={commands}
-                    onExit={onExit}
-                >
-                    <LogsProvider>
-                        <ExecutorProvider>
-                            <NavigationProvider<CommandSelectParams>
-                                initialScreen={{ route: CommandSelectScreen.Id, params: { commandPath: [] } }}
-                                onExit={onExit}
-                            >
-                                <TuiRootContent />
-                            </NavigationProvider>
-                        </ExecutorProvider>
-                    </LogsProvider>
-                </TuiAppContextProvider>
-            </ClipboardProviderComponent>
-        </KeyboardProvider>
+        <TuiAppContextProvider
+            name={name}
+            displayName={displayName}
+            version={version}
+            commands={commands}
+            onExit={onExit}
+        >
+            <LogsProvider>
+                <ExecutorProvider>
+                    <NavigationProvider<{ commandPath: string[] }>
+                        initialScreen={{ route: "commandBrowser", params: { commandPath: [] as string[] } }}
+                        onExit={onExit}
+                    >
+                        <TuiDriverProvider appName={name} commands={commands}>
+                            <TuiRootContent />
+                        </TuiDriverProvider>
+                    </NavigationProvider>
+                </ExecutorProvider>
+            </LogsProvider>
+        </TuiAppContextProvider>
     );
 }
 
@@ -55,81 +49,43 @@ export function TuiRoot({ name, displayName, version, commands, onExit }: TuiRoo
  */
 function TuiRootContent() {
     const { displayName, name, version } = useTuiApp();
+    const driver = useTuiDriver();
     const navigation = useNavigation();
-    const executor = useExecutor();
-    const clipboard = useClipboardContext();
-    const { copyWithMessage, lastAction } = useClipboard();
-    
-
+    const [copyToast, setCopyToast] = useState<string | null>(null);
 
-    // Global keyboard handler - only truly global shortcuts
-    useGlobalKeyHandler((key) => {
-        // Esc - back/close (delegates to navigation which delegates to screen)
-        if (key.name === "escape") {
-            navigation.goBack();
-            return true;
-        }
-
-        // Ctrl+Y - copy
-        if (key.ctrl && key.name === "y") {
-            const content = clipboard.getContent();
-            if (content) {
-                copyWithMessage(content.content, content.label);
-            }
-            return true;
-        }
+    return (
+        <ActionProvider navigation={navigation}>
+            <TuiRootKeyboardHandler onCopyToastChange={setCopyToast} />
+            {driver.renderAppShell({
+                app: {
+                    name,
+                    displayName,
+                    version,
+                },
+                copyToast,
+            })}
+        </ActionProvider>
+    );
+}
 
-        // Ctrl+L - toggle logs modal
-        if (key.ctrl && key.name === "l") {
-            const isLogsOpen = navigation.modalStack.some((m) => m.id === "logs");
-            if (isLogsOpen) {
-                navigation.closeModal();
-            } else {
-                 navigation.openModal("logs");
+/**
+ * Renders the adapter-specific keyboard handler component.
+ * This component uses hooks properly since it's rendered as a React component.
+ */
+function TuiRootKeyboardHandler({ onCopyToastChange }: { onCopyToastChange: (toast: string | null) => void }) {
+    const renderer = useRenderer();
+    const { dispatchAction } = useAction();
 
-            }
-            return true;
-        }
+    if (!renderer.renderKeyboardHandler) {
+        return null;
+    }
 
-        return false;
+    return renderer.renderKeyboardHandler({ 
+        dispatchAction, 
+        getScreenKeyHandler: () => null,
+        onCopyToastChange,
     });
+}
 
-    // Get current screen component from registry
-    const ScreenComponent = getScreen(navigation.current.route);
-    
-    // Get breadcrumb from current screen params (if available)
-    const params = navigation.current.params as { commandPath?: string[] } | undefined;
-    const breadcrumb = params?.commandPath;
-
-    return (
-        <Panel flexDirection="column" flex={1} padding={1} border={false}>
-            <Container flexDirection="column" flex={1}>
-                <Header name={displayName ?? name} version={version} breadcrumb={breadcrumb} />
-
-            <Container flexDirection="column" flex={1}>
-                {ScreenComponent ? <ScreenComponent /> : null}
-            </Container>
-
-            <StatusBar
-                status={lastAction || (executor.isExecuting ? "Executing..." : "Ready")}
-                isRunning={executor.isExecuting}
-                shortcuts="Esc Back • Ctrl+Y Copy • Ctrl+L Logs"
-            />
 
-            {/* Render modals from registry */}
-            {navigation.modalStack.map((modal, idx) => {
-                const ModalComponent = getModal(modal.id);
-                if (!ModalComponent) return null;
 
-                return (
-                    <ModalComponent
-                        key={`modal-${modal.id}-${idx}`}
-                        params={modal.params}
-                        onClose={() => navigation.closeModal()}
-                    />
-                );
-            })}
-            </Container>
-        </Panel>
-    );
-}

package/src/tui/actions.ts

@@ -0,0 +1,4 @@
+export type TuiAction =
+    | { type: "nav.back" }
+    | { type: "copy" }
+    | { type: "logs.open" };

package/src/tui/adapters/ink/InkRenderer.tsx

@@ -1,28 +1,180 @@
 import { render } from "ink";
 import type { ReactNode } from "react";
-import { useLayoutEffect } from "react";
+import { useEffect, useLayoutEffect } from "react";
 
-import type { Renderer, RendererConfig } from "../types.ts";
+import type { KeyboardEvent, Renderer, RendererConfig } from "../types.ts";
+import { SemanticInkRenderer } from "./SemanticInkRenderer.tsx";
 import { useInkKeyboardAdapter } from "./keyboard.ts";
+import { copyToTerminalClipboard } from "../shared/TerminalClipboard.ts";
+import { useTuiDriver } from "../../driver/context/TuiDriverContext.tsx";
 
-import { Button } from "./components/Button.tsx";
-import { Container } from "./components/Container.tsx";
-import { Field } from "./components/Field.tsx";
-import { Label } from "./components/Label.tsx";
-import { MenuButton } from "./components/MenuButton.tsx";
-import { MenuItem } from "./components/MenuItem.tsx";
-import { Overlay } from "./components/Overlay.tsx";
-import { Panel } from "./components/Panel.tsx";
-import { ScrollView } from "./components/ScrollView.tsx";
-import { Select } from "./components/Select.tsx";
-import { Spacer } from "./components/Spacer.tsx";
-import { Spinner } from "./components/Spinner.tsx";
-import { TextInput } from "./components/TextInput.tsx";
-import { Value } from "./components/Value.tsx";
-import { Code } from "./components/Code.tsx";
-import { CodeHighlight } from "./components/CodeHighlight.tsx";
+import type { TuiAction } from "../../actions.ts";
+
+function InkKeyboardHandler({
+    dispatchAction,
+    getScreenKeyHandler,
+    keyboard,
+    onCopyToastChange,
+}: {
+    dispatchAction: (action: TuiAction) => void;
+    getScreenKeyHandler: () => ((event: KeyboardEvent) => boolean) | null;
+    keyboard: Renderer["keyboard"];
+    onCopyToastChange?: (toast: string | null) => void;
+}) {
+    const driver = useTuiDriver();
+
+    useEffect(() => {
+        const cleanup = keyboard.setGlobalHandler((event) => {
+            // Debug: log keyboard events
+            // console.log("Key event:", event.name, "screenHandler:", getScreenKeyHandler() ? "yes" : "no");
+            
+            if (event.name === "escape") {
+                dispatchAction({ type: "nav.back" });
+                return true;
+            }
+
+            if (event.ctrl && event.name === "y") {
+                const payload = driver.getActiveCopyPayload();
+                if (payload) {
+                    // Show toast immediately for instant feedback
+                    onCopyToastChange?.(`Copied ${payload.label}`);
+                    void copyToTerminalClipboard(payload.content).then((success) => {
+                        if (!success) {
+                            onCopyToastChange?.("Copy failed");
+                        }
+                        setTimeout(() => onCopyToastChange?.(null), 1500);
+                    });
+                }
+                return true;
+            }
+
+            if (event.ctrl && event.name === "l") {
+                dispatchAction({ type: "logs.open" });
+                return true;
+            }
+
+            const screenHandler = getScreenKeyHandler();
+            if (screenHandler) {
+                return screenHandler(event);
+            }
+
+            return false;
+        });
+
+        return cleanup;
+    }, [dispatchAction, getScreenKeyHandler, keyboard, driver, onCopyToastChange]);
+
+    return null;
+}
 
 export class InkRenderer implements Renderer {
+
+    private readonly semanticRenderer = new SemanticInkRenderer();
+
+    private semanticScreenKeyHandler: ((event: KeyboardEvent) => boolean) | null = null;
+
+    public renderSemanticAppShell: Renderer["renderSemanticAppShell"] = (props) => {
+        return this.semanticRenderer.renderAppShell(props);
+    };
+    public renderSemanticCommandBrowserScreen: Renderer["renderSemanticCommandBrowserScreen"] = (props) => {
+        this.semanticScreenKeyHandler = (event) => {
+            if (event.ctrl && event.name === "l") {
+                // Logs open is adapter-owned.
+                return false;
+            }
+
+            if (event.name === "up") {
+                props.onSelectCommand(props.selectedCommandIndex - 1);
+                return true;
+            }
+
+            if (event.name === "down") {
+                props.onSelectCommand(props.selectedCommandIndex + 1);
+                return true;
+            }
+
+            if (event.name === "return") {
+                props.onRunSelected();
+                return true;
+            }
+
+            return false;
+        };
+
+        return this.semanticRenderer.renderCommandBrowserScreen(props);
+    };
+
+    public renderSemanticConfigScreen: Renderer["renderSemanticConfigScreen"] = (props) => {
+        this.semanticScreenKeyHandler = (event) => {
+            if (event.ctrl && event.name === "l") {
+                // Adapter-owned logs open.
+                return false;
+            }
+
+            if (event.name === "up") {
+                props.onSelectionChange(props.selectedFieldIndex - 1);
+                return true;
+            }
+
+            if (event.name === "down") {
+                props.onSelectionChange(props.selectedFieldIndex + 1);
+                return true;
+            }
+
+            if (event.name === "return") {
+                const fieldConfig = props.fieldConfigs[props.selectedFieldIndex];
+                if (fieldConfig) {
+                    props.onEditField(fieldConfig.key);
+                } else {
+                    props.onRun();
+                }
+                return true;
+            }
+
+            return false;
+        };
+
+        return this.semanticRenderer.renderConfigScreen(props);
+    };
+    public renderSemanticRunningScreen: Renderer["renderSemanticRunningScreen"] = (props) => {
+        this.semanticScreenKeyHandler = null;
+        return this.semanticRenderer.renderRunningScreen(props);
+    };
+    public renderSemanticLogsScreen: Renderer["renderSemanticLogsScreen"] = (props) => {
+        this.semanticScreenKeyHandler = (event) => {
+            if (event.name === "return") {
+                props.onClose();
+                return true;
+            }
+            return false;
+        };
+
+        return this.semanticRenderer.renderLogsScreen(props);
+    };
+
+    public renderSemanticEditorScreen: Renderer["renderSemanticEditorScreen"] = (props) => {
+        this.semanticScreenKeyHandler = (event) => {
+            if (event.name === "return") {
+                props.onSubmit?.();
+                return true;
+            }
+            return false;
+        };
+
+        return this.semanticRenderer.renderEditorScreen(props);
+    };
+
+    public renderKeyboardHandler: Renderer["renderKeyboardHandler"] = ({ dispatchAction, onCopyToastChange }) => {
+        return (
+            <InkKeyboardHandlerWrapper
+                dispatchAction={dispatchAction}
+                getScreenKeyHandler={() => this.semanticScreenKeyHandler}
+                keyboard={this.keyboard}
+                onCopyToastChange={onCopyToastChange}
+            />
+        );
+    };
+
     private instance: ReturnType<typeof render> | null = null;
     private activeKeyboardAdapter: Renderer["keyboard"] | null = null;
 
@@ -35,29 +187,6 @@ export class InkRenderer implements Renderer {
         },
     };
 
-    public components: Renderer["components"] = {
-        Field,
-        Button,
-        MenuButton,
-        MenuItem,
-
-        Container,
-        Panel,
-        ScrollView,
-
-        Overlay,
-        Spacer,
-        Spinner,
-
-        Label,
-        Value,
-        Code,
-        CodeHighlight,
-
-        Select,
-        TextInput,
-    };
-
     constructor(_config: RendererConfig) {}
 
     async initialize(): Promise<void> {
@@ -133,3 +262,24 @@ function KeyboardBridge({
 
     return node;
 }
+
+function InkKeyboardHandlerWrapper({
+    dispatchAction,
+    getScreenKeyHandler,
+    keyboard,
+    onCopyToastChange,
+}: {
+    dispatchAction: (action: TuiAction) => void;
+    getScreenKeyHandler: () => ((event: KeyboardEvent) => boolean) | null;
+    keyboard: Renderer["keyboard"];
+    onCopyToastChange?: (toast: string | null) => void;
+}) {
+    return (
+        <InkKeyboardHandler
+            dispatchAction={dispatchAction}
+            getScreenKeyHandler={getScreenKeyHandler}
+            keyboard={keyboard}
+            onCopyToastChange={onCopyToastChange}
+        />
+    );
+}