@pokit/tabs-core 0.0.1 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pokit/tabs-core",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Core tab management utilities for pok CLI applications",
   "keywords": [
     "cli",
@@ -25,9 +25,8 @@
   "bugs": {
     "url": "https://github.com/notation-dev/openpok/issues"
   },
-  "main": "./src/index.ts",
-  "module": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "bun": "./src/index.ts",
@@ -38,14 +37,15 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src"
   ],
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
-    "@pokit/core": "0.0.1"
+    "@pokit/core": "0.0.3"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -56,7 +56,7 @@
     "@types/bun": "latest",
     "@types/react": "^19.2.0",
     "react": "^19.2.0",
-    "@pokit/core": "0.0.1"
+    "@pokit/core": "0.0.3"
   },
   "engines": {
     "bun": ">=1.0.0"

package/src/constants/help-content.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared Help Content for CLI Tabs
+ *
+ * Keyboard shortcut definitions and help overlay content used by all adapters.
+ */
+
+export type Shortcut = {
+  key: string;
+  description: string;
+};
+
+export type ShortcutGroup = {
+  title: string;
+  shortcuts: Shortcut[];
+};
+
+/**
+ * Standard keyboard shortcut help content.
+ * Used by both Ink and OpenTUI help overlays.
+ */
+export const HELP_CONTENT: ShortcutGroup[] = [
+  {
+    title: 'Navigation',
+    shortcuts: [
+      { key: '\u2191/\u2193', description: 'Scroll output up/down' },
+      { key: 'Page Up/Dn', description: 'Scroll by page' },
+      { key: 'Tab', description: 'Next tab' },
+      { key: 'Shift+Tab', description: 'Previous tab' },
+      { key: '1-9', description: 'Jump to tab by number' },
+      { key: 'Meta+\u2190/\u2192', description: 'Previous/next tab' },
+    ],
+  },
+  {
+    title: 'Process Control',
+    shortcuts: [
+      { key: 'r', description: 'Restart current process' },
+      { key: 'k', description: 'Kill current process' },
+      { key: 'q', description: 'Quit (with confirmation)' },
+      { key: 'Ctrl+C', description: 'Force quit immediately' },
+    ],
+  },
+  {
+    title: 'Input Mode',
+    shortcuts: [
+      { key: 'i', description: 'Enter input mode' },
+      { key: 'Escape', description: 'Exit input mode' },
+    ],
+  },
+];

package/src/constants/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Constants Index
+ *
+ * Re-exports all shared constants for CLI tabs.
+ */
+
+export type { Shortcut, ShortcutGroup } from './help-content.js';
+export { HELP_CONTENT } from './help-content.js';
+
+export { KEY_SEQUENCES, ctrlKeyToSequence, HELP_HINT_DURATION_MS } from './keyboard.js';

package/src/constants/keyboard.ts

@@ -0,0 +1,37 @@
+/**
+ * Keyboard Constants for CLI Tabs
+ *
+ * Escape sequences and key mappings for terminal input handling.
+ */
+
+/**
+ * Common terminal escape sequences for special keys.
+ * Used when forwarding input to child processes in focus mode.
+ */
+export const KEY_SEQUENCES = {
+  RETURN: '\n',
+  TAB: '\t',
+  BACKSPACE: '\x7f',
+  DELETE: '\x1b[3~',
+  ARROW_UP: '\x1b[A',
+  ARROW_DOWN: '\x1b[B',
+  ARROW_RIGHT: '\x1b[C',
+  ARROW_LEFT: '\x1b[D',
+} as const;
+
+/**
+ * Convert a Ctrl+key combination to its terminal escape sequence.
+ * Ctrl+A = 1, Ctrl+B = 2, ..., Ctrl+Z = 26
+ */
+export function ctrlKeyToSequence(key: string): string | null {
+  const code = key.toUpperCase().charCodeAt(0) - 64;
+  if (code >= 1 && code <= 26) {
+    return String.fromCharCode(code);
+  }
+  return null;
+}
+
+/**
+ * Duration to show help hint on startup (in milliseconds).
+ */
+export const HELP_HINT_DURATION_MS = 5000;

package/src/hooks/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Hooks Index
+ *
+ * Re-exports all shared hooks for CLI tabs.
+ */
+
+export type { UseTabsStateOptions, TabsState, TabsActions } from './use-tabs-state.js';
+export { useTabsState } from './use-tabs-state.js';
+
+export type {
+  KeyboardCallbacks,
+  KeyboardState,
+  NormalizedKeyEvent,
+  KeyboardAction,
+} from './use-keyboard-handler.js';
+export {
+  processKeyEvent,
+  useKeyboardCallbackRefs,
+  executeKeyboardAction,
+} from './use-keyboard-handler.js';

package/src/hooks/use-keyboard-handler.ts

@@ -0,0 +1,318 @@
+/**
+ * Shared Keyboard Handler Logic
+ *
+ * Framework-agnostic keyboard action handling for tabbed terminal interfaces.
+ * Provides normalized keyboard actions that can be called by framework-specific handlers.
+ */
+
+import { useRef, useEffect } from 'react';
+import { KEY_SEQUENCES, ctrlKeyToSequence } from '../constants/keyboard.js';
+
+/**
+ * Callbacks for keyboard actions in the tabbed view.
+ */
+export type KeyboardCallbacks = {
+  onQuit: () => void;
+  onQuitRequest: () => void;
+  onRestart: (index: number) => void;
+  onKill: (index: number) => void;
+  onEnterFocusMode: () => void;
+  onExitFocusMode: () => void;
+  onSendInput: (data: string) => void;
+  onToggleHelp: () => void;
+  onCloseHelp: () => void;
+};
+
+/**
+ * Current state needed for keyboard handling decisions.
+ */
+export type KeyboardState = {
+  helpVisible: boolean;
+  focusMode: boolean;
+  quitConfirmPending: boolean;
+  activeIndex: number;
+  tabCount: number;
+};
+
+/**
+ * Normalized key event structure.
+ * Provides a unified interface for different terminal keyboard APIs.
+ */
+export type NormalizedKeyEvent = {
+  /** The character(s) typed, if any */
+  char?: string;
+  /** Named key (e.g., 'escape', 'tab', 'up', 'down') */
+  name?: string;
+  /** Whether Ctrl was held */
+  ctrl?: boolean;
+  /** Whether Shift was held */
+  shift?: boolean;
+  /** Whether Meta/Alt was held */
+  meta?: boolean;
+};
+
+/**
+ * Action results from keyboard handling.
+ */
+export type KeyboardAction =
+  | { type: 'toggle-help' }
+  | { type: 'close-help' }
+  | { type: 'exit-focus-mode' }
+  | { type: 'send-input'; data: string }
+  | { type: 'quit' }
+  | { type: 'quit-request' }
+  | { type: 'cancel-quit' }
+  | { type: 'enter-focus-mode' }
+  | { type: 'restart'; index: number }
+  | { type: 'kill'; index: number }
+  | { type: 'switch-tab'; index: number }
+  | { type: 'next-tab' }
+  | { type: 'prev-tab' }
+  | { type: 'scroll'; delta: number }
+  | { type: 'none' };
+
+/**
+ * Process a normalized key event and return the appropriate action.
+ *
+ * This is the core keyboard handling logic, extracted to be framework-agnostic.
+ * Each adapter (Ink, OpenTUI) normalizes their keyboard events and calls this function.
+ */
+export function processKeyEvent(
+  event: NormalizedKeyEvent,
+  state: KeyboardState,
+  viewHeight: number
+): KeyboardAction {
+  const { char, name, ctrl, shift, meta } = event;
+  const { helpVisible, focusMode, quitConfirmPending, activeIndex, tabCount } = state;
+
+  // Help toggle takes priority
+  if (char === '?') {
+    return { type: 'toggle-help' };
+  }
+
+  // Escape closes help if visible
+  if (name === 'escape' && helpVisible) {
+    return { type: 'close-help' };
+  }
+
+  // Don't process other keys when help is visible
+  if (helpVisible) {
+    return { type: 'none' };
+  }
+
+  // Focus mode: forward most input to child process
+  if (focusMode) {
+    if (name === 'escape') {
+      return { type: 'exit-focus-mode' };
+    }
+
+    const rawInput = getFocusModeInput(event);
+    if (rawInput) {
+      return { type: 'send-input', data: rawInput };
+    }
+    return { type: 'none' };
+  }
+
+  // Normal mode: handle UI navigation
+
+  // Quit confirmation handling
+  if (quitConfirmPending) {
+    if (char === 'q' || name === 'q') {
+      return { type: 'quit' };
+    }
+    return { type: 'cancel-quit' };
+  }
+
+  // Quit request
+  if (char === 'q' || name === 'q') {
+    return { type: 'quit-request' };
+  }
+
+  // Ctrl+C for instant quit
+  if ((char === 'c' || name === 'c') && ctrl) {
+    return { type: 'quit' };
+  }
+
+  // Enter focus/input mode
+  if (char === 'i' || name === 'i') {
+    return { type: 'enter-focus-mode' };
+  }
+
+  // Restart current tab
+  if (char === 'r' || name === 'r') {
+    return { type: 'restart', index: activeIndex };
+  }
+
+  // Kill current tab's process
+  if (char === 'k' || name === 'k') {
+    return { type: 'kill', index: activeIndex };
+  }
+
+  // Number keys 1-9 for direct tab access
+  const input = char || name || '';
+  const num = parseInt(input, 10);
+  if (num >= 1 && num <= tabCount) {
+    return { type: 'switch-tab', index: num - 1 };
+  }
+
+  // Tab navigation
+  if (name === 'tab' && shift) {
+    return { type: 'prev-tab' };
+  }
+  if (name === 'tab') {
+    return { type: 'next-tab' };
+  }
+
+  // Arrow key tab navigation (with meta)
+  if ((name === 'left' || name === 'leftArrow') && meta) {
+    return { type: 'prev-tab' };
+  }
+  if ((name === 'right' || name === 'rightArrow') && meta) {
+    return { type: 'next-tab' };
+  }
+
+  // Scrolling
+  if (name === 'up' || name === 'upArrow') {
+    return { type: 'scroll', delta: -1 };
+  }
+  if (name === 'down' || name === 'downArrow') {
+    return { type: 'scroll', delta: 1 };
+  }
+  if (name === 'pageup' || name === 'pageUp') {
+    return { type: 'scroll', delta: -viewHeight };
+  }
+  if (name === 'pagedown' || name === 'pageDown') {
+    return { type: 'scroll', delta: viewHeight };
+  }
+
+  return { type: 'none' };
+}
+
+/**
+ * Get the raw input to send to child process when in focus mode.
+ */
+function getFocusModeInput(event: NormalizedKeyEvent): string | null {
+  const { char, name, ctrl } = event;
+
+  // Map special keys to escape sequences
+  if (name === 'return') return KEY_SEQUENCES.RETURN;
+  if (name === 'tab') return KEY_SEQUENCES.TAB;
+  if (name === 'backspace') return KEY_SEQUENCES.BACKSPACE;
+  if (name === 'delete') return KEY_SEQUENCES.DELETE;
+  if (name === 'up' || name === 'upArrow') return KEY_SEQUENCES.ARROW_UP;
+  if (name === 'down' || name === 'downArrow') return KEY_SEQUENCES.ARROW_DOWN;
+  if (name === 'right' || name === 'rightArrow') return KEY_SEQUENCES.ARROW_RIGHT;
+  if (name === 'left' || name === 'leftArrow') return KEY_SEQUENCES.ARROW_LEFT;
+
+  // Ctrl+key combinations
+  if (ctrl && name && name.length === 1) {
+    return ctrlKeyToSequence(name);
+  }
+
+  // Regular character input
+  if (char) {
+    return char;
+  }
+
+  return null;
+}
+
+/**
+ * Hook to create stable references for keyboard callbacks.
+ *
+ * This solves the common React issue where callbacks in keyboard handlers
+ * may have stale closures. The refs always point to the current callback.
+ */
+export function useKeyboardCallbackRefs(callbacks: KeyboardCallbacks) {
+  const onQuitRef = useRef(callbacks.onQuit);
+  const onQuitRequestRef = useRef(callbacks.onQuitRequest);
+  const onRestartRef = useRef(callbacks.onRestart);
+  const onKillRef = useRef(callbacks.onKill);
+  const onEnterFocusModeRef = useRef(callbacks.onEnterFocusMode);
+  const onExitFocusModeRef = useRef(callbacks.onExitFocusMode);
+  const onSendInputRef = useRef(callbacks.onSendInput);
+  const onToggleHelpRef = useRef(callbacks.onToggleHelp);
+  const onCloseHelpRef = useRef(callbacks.onCloseHelp);
+
+  useEffect(() => {
+    onQuitRef.current = callbacks.onQuit;
+    onQuitRequestRef.current = callbacks.onQuitRequest;
+    onRestartRef.current = callbacks.onRestart;
+    onKillRef.current = callbacks.onKill;
+    onEnterFocusModeRef.current = callbacks.onEnterFocusMode;
+    onExitFocusModeRef.current = callbacks.onExitFocusMode;
+    onSendInputRef.current = callbacks.onSendInput;
+    onToggleHelpRef.current = callbacks.onToggleHelp;
+    onCloseHelpRef.current = callbacks.onCloseHelp;
+  }, [callbacks]);
+
+  return {
+    onQuitRef,
+    onQuitRequestRef,
+    onRestartRef,
+    onKillRef,
+    onEnterFocusModeRef,
+    onExitFocusModeRef,
+    onSendInputRef,
+    onToggleHelpRef,
+    onCloseHelpRef,
+  };
+}
+
+/**
+ * Execute a keyboard action using the provided callback refs.
+ */
+export function executeKeyboardAction(
+  action: KeyboardAction,
+  refs: ReturnType<typeof useKeyboardCallbackRefs>,
+  scrollBy: (delta: number) => void,
+  switchTab: (index: number) => void,
+  nextTab: () => void,
+  prevTab: () => void
+): void {
+  switch (action.type) {
+    case 'toggle-help':
+      refs.onToggleHelpRef.current();
+      break;
+    case 'close-help':
+      refs.onCloseHelpRef.current();
+      break;
+    case 'exit-focus-mode':
+      refs.onExitFocusModeRef.current();
+      break;
+    case 'send-input':
+      refs.onSendInputRef.current(action.data);
+      break;
+    case 'quit':
+      refs.onQuitRef.current();
+      break;
+    case 'quit-request':
+    case 'cancel-quit':
+      refs.onQuitRequestRef.current();
+      break;
+    case 'enter-focus-mode':
+      refs.onEnterFocusModeRef.current();
+      break;
+    case 'restart':
+      refs.onRestartRef.current(action.index);
+      break;
+    case 'kill':
+      refs.onKillRef.current(action.index);
+      break;
+    case 'switch-tab':
+      switchTab(action.index);
+      break;
+    case 'next-tab':
+      nextTab();
+      break;
+    case 'prev-tab':
+      prevTab();
+      break;
+    case 'scroll':
+      scrollBy(action.delta);
+      break;
+    case 'none':
+      // Do nothing
+      break;
+  }
+}

package/src/hooks/use-tabs-state.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared Tab State Management Hook
+ *
+ * Framework-agnostic state management for tabbed terminal interfaces.
+ * Handles tab selection, scroll offsets, auto-scroll behavior, and help hint visibility.
+ */
+
+import { useState, useEffect, useCallback } from 'react';
+import type { TabProcess } from '../types.js';
+import { HELP_HINT_DURATION_MS } from '../constants/keyboard.js';
+
+export type UseTabsStateOptions = {
+  /** List of tab processes */
+  tabs: TabProcess[];
+  /** Current active tab index */
+  activeIndex: number;
+  /** Callback when active index changes */
+  onActiveIndexChange: (index: number) => void;
+  /** Height of the output view in lines */
+  viewHeight: number;
+};
+
+export type TabsState = {
+  /** Whether to show the help hint */
+  showHelpHint: boolean;
+  /** Current scroll offset for the active tab */
+  activeScrollOffset: number;
+  /** Whether the user can scroll up */
+  canScrollUp: boolean;
+  /** Whether the user can scroll down */
+  canScrollDown: boolean;
+};
+
+export type TabsActions = {
+  /** Scroll by a given delta (positive = down, negative = up) */
+  scrollBy: (delta: number) => void;
+  /** Switch to a specific tab by index */
+  switchTab: (index: number) => void;
+  /** Switch to the next tab (wraps around) */
+  nextTab: () => void;
+  /** Switch to the previous tab (wraps around) */
+  prevTab: () => void;
+};
+
+/**
+ * Hook for managing tabbed interface state.
+ *
+ * Provides:
+ * - Per-tab scroll offsets with auto-scroll behavior
+ * - Tab navigation helpers
+ * - Help hint auto-dismiss timer
+ */
+export function useTabsState({
+  tabs,
+  activeIndex,
+  onActiveIndexChange,
+  viewHeight,
+}: UseTabsStateOptions): TabsState & TabsActions {
+  // Show help hint for first N seconds
+  const [showHelpHint, setShowHelpHint] = useState(true);
+  useEffect(() => {
+    const timer = setTimeout(() => setShowHelpHint(false), HELP_HINT_DURATION_MS);
+    return () => clearTimeout(timer);
+  }, []);
+
+  // Per-tab scroll offsets
+  const [scrollOffsets, setScrollOffsets] = useState<Map<string, number>>(() => new Map());
+  // Per-tab auto-scroll state
+  const [autoScroll, setAutoScroll] = useState<Map<string, boolean>>(
+    () => new Map(tabs.map((t) => [t.id, true]))
+  );
+
+  const activeTab = tabs[activeIndex];
+  const activeScrollOffset = scrollOffsets.get(activeTab?.id ?? '') ?? 0;
+
+  // Calculate scroll state
+  const totalLines = activeTab?.output.length ?? 0;
+  const maxScroll = Math.max(0, totalLines - viewHeight);
+  const canScrollUp = activeScrollOffset > 0;
+  const canScrollDown = activeScrollOffset < maxScroll;
+
+  // Auto-scroll when new output arrives (if auto-scroll enabled for this tab)
+  useEffect(() => {
+    if (!activeTab) return;
+    const shouldAutoScroll = autoScroll.get(activeTab.id) ?? true;
+    if (shouldAutoScroll) {
+      const maxScroll = Math.max(0, activeTab.output.length - viewHeight);
+      setScrollOffsets((prev: Map<string, number>) => {
+        const next = new Map(prev);
+        next.set(activeTab.id, maxScroll);
+        return next;
+      });
+    }
+  }, [activeTab, viewHeight, autoScroll]);
+
+  const scrollBy = useCallback(
+    (delta: number) => {
+      if (!activeTab) return;
+      const maxScroll = Math.max(0, activeTab.output.length - viewHeight);
+      setScrollOffsets((prev: Map<string, number>) => {
+        const next = new Map(prev);
+        const current = prev.get(activeTab.id) ?? 0;
+        const newOffset = Math.max(0, Math.min(maxScroll, current + delta));
+        next.set(activeTab.id, newOffset);
+
+        // If scrolled away from bottom, disable auto-scroll
+        // If scrolled to bottom, re-enable auto-scroll
+        const atBottom = newOffset >= maxScroll;
+        setAutoScroll((as: Map<string, boolean>) => {
+          const asNext = new Map(as);
+          asNext.set(activeTab.id, atBottom);
+          return asNext;
+        });
+
+        return next;
+      });
+    },
+    [activeTab, viewHeight]
+  );
+
+  const switchTab = useCallback(
+    (newIndex: number) => {
+      if (newIndex >= 0 && newIndex < tabs.length) {
+        onActiveIndexChange(newIndex);
+      }
+    },
+    [tabs.length, onActiveIndexChange]
+  );
+
+  const nextTab = useCallback(() => {
+    switchTab((activeIndex + 1) % tabs.length);
+  }, [activeIndex, tabs.length, switchTab]);
+
+  const prevTab = useCallback(() => {
+    switchTab((activeIndex - 1 + tabs.length) % tabs.length);
+  }, [activeIndex, tabs.length, switchTab]);
+
+  return {
+    // State
+    showHelpHint,
+    activeScrollOffset,
+    canScrollUp,
+    canScrollDown,
+    // Actions
+    scrollBy,
+    switchTab,
+    nextTab,
+    prevTab,
+  };
+}