@navios/commander-tui 1.0.0

package/src/types/keyboard.types.ts

@@ -0,0 +1,93 @@
+import type { FocusArea } from './screen.types.ts'
+
+// ============================================
+// Keyboard Event Types
+// ============================================
+
+/**
+ * Key event from the terminal.
+ */
+export interface KeyEvent {
+  name: string
+  sequence?: string
+  ctrl?: boolean
+  meta?: boolean
+  shift?: boolean
+}
+
+/**
+ * Context available to keyboard handlers.
+ */
+export interface KeyboardContext {
+  /** Has multiple screens (sidebar visible) */
+  hasSidebar: boolean
+  /** Currently focused area */
+  focusArea: FocusArea
+  /** Whether a prompt is active */
+  hasPrompt: boolean
+  /** Whether prompt is in text input mode */
+  inInputMode: boolean
+  /** Whether filter bar is visible */
+  isFilterActive: boolean
+  /** Whether help overlay is visible */
+  isHelpVisible: boolean
+}
+
+/**
+ * Handler function for a key binding.
+ * Return true to prevent further processing, false/void to continue.
+ */
+export type KeyHandler = (key: KeyEvent, context: KeyboardContext) => boolean | void
+
+/**
+ * Category for organizing bindings in help overlay.
+ */
+export type KeyBindingCategory = 'general' | 'navigation' | 'screen' | 'prompt' | 'filter'
+
+/**
+ * Condition for when a binding is active.
+ */
+export interface KeyBindingCondition {
+  hasPrompt?: boolean
+  inInputMode?: boolean
+  focusArea?: FocusArea
+  isFilterActive?: boolean
+  isHelpVisible?: boolean
+  hasSidebar?: boolean
+}
+
+/**
+ * A single key binding definition.
+ */
+export interface KeyBinding {
+  /** Key name(s) that trigger this binding */
+  key: string | string[]
+  /** Require Ctrl modifier */
+  ctrl?: boolean
+  /** Require Meta/Cmd modifier */
+  meta?: boolean
+  /** Require Shift modifier (for capital letters) */
+  shift?: boolean
+  /** Handler function */
+  handler: KeyHandler
+  /** Description for help overlay */
+  description: string
+  /** Category for grouping in help */
+  category: KeyBindingCategory
+  /** Condition when this binding is active */
+  when?: KeyBindingCondition
+  /** Priority (higher = checked first, default 0) */
+  priority?: number
+}
+
+/**
+ * Configuration for the keyboard manager.
+ */
+export interface KeyBindingsConfig {
+  /** Custom bindings (added to defaults) */
+  bindings?: KeyBinding[]
+  /** Override specific default bindings by key */
+  overrides?: Record<string, Partial<KeyBinding>>
+  /** Disable specific keys */
+  disabled?: string[]
+}

package/src/types/log.types.ts

@@ -0,0 +1,61 @@
+import type { LogLevel } from '@navios/core'
+import type { RGBA } from '@opentui/core'
+import type { ReactNode } from 'react'
+
+import type { LogMessageVariant } from './message.types.ts'
+
+// ============================================
+// Log Level Types
+// ============================================
+
+export interface LogLevelColors {
+  border: string
+  background: string
+  text?: string
+}
+
+export type LogLevelColorMap = Record<LogLevel, LogLevelColors>
+
+/**
+ * Color map for semantic variants (success, trace) that override level colors.
+ */
+export type VariantColorMap = Record<LogMessageVariant, LogLevelColors>
+
+// ============================================
+// LogMessage Component Types
+// ============================================
+
+export interface LogMessageProps {
+  /** Log level determines the color scheme */
+  level: LogLevel
+
+  /** Optional semantic variant for styling (e.g., 'success' shows green even though level is 'log') */
+  variant?: LogMessageVariant
+
+  /** Message content - can be string or React nodes */
+  children: ReactNode
+
+  /** Optional timestamp to display */
+  timestamp?: Date | string
+
+  /** Optional label/prefix (e.g., "API", "Database") */
+  label?: string
+
+  /** Optional stack trace to display (for trace level) */
+  trace?: string
+
+  /** Optional custom border color (overrides level color) */
+  borderColor?: string | RGBA
+
+  /** Optional custom background color (overrides level color) */
+  backgroundColor?: string | RGBA
+
+  /** Border width style - 'thin' uses left border only, 'thick' uses left+top+bottom */
+  borderStyle?: 'thin' | 'thick'
+
+  /** Padding inside the message box */
+  padding?: number
+
+  /** Margin around the message */
+  margin?: number
+}

package/src/types/message.types.ts

@@ -0,0 +1,120 @@
+import type { LogLevel } from '@navios/core'
+
+// ============================================
+// Internal Message Types
+// ============================================
+
+export type MessageType =
+  | 'log'
+  | 'file'
+  | 'diff'
+  | 'fileError'
+  | 'loading'
+  | 'progress'
+  | 'group'
+  | 'table'
+
+export interface BaseMessage {
+  id: string
+  type: MessageType
+  timestamp: Date
+}
+
+/**
+ * Semantic variants for log messages that don't map directly to LogLevel.
+ * These affect styling but the underlying LogLevel is used for filtering.
+ */
+export type LogMessageVariant = 'success' | 'trace'
+
+export interface LogMessageData extends BaseMessage {
+  type: 'log'
+  level: LogLevel
+  /** Content is always a string - objects are formatted before storage */
+  content: string
+  label?: string
+  trace?: string
+  /** Optional semantic variant for styling (e.g., 'success' shows green even though level is 'log') */
+  variant?: LogMessageVariant
+}
+
+export interface FileMessageData extends BaseMessage {
+  type: 'file'
+  filePath: string
+  content: string
+}
+
+export interface DiffMessageData extends BaseMessage {
+  type: 'diff'
+  filePath: string
+  diff: string
+  view?: 'unified' | 'split'
+}
+
+export interface FileErrorMessageData extends BaseMessage {
+  type: 'fileError'
+  filePath: string
+  content: string
+  errorLines: number[]
+  startLine: number
+}
+
+export interface LoadingMessageData extends BaseMessage {
+  type: 'loading'
+  content: string
+  status: 'loading' | 'success' | 'fail'
+  resolvedContent?: string
+}
+
+export interface ProgressMessageData extends BaseMessage {
+  type: 'progress'
+  label: string
+  current: number
+  total: number
+  status: 'active' | 'complete' | 'failed'
+  resolvedContent?: string
+}
+
+export interface GroupMessageData extends BaseMessage {
+  type: 'group'
+  label: string
+  collapsed: boolean
+  isEnd: boolean
+}
+
+export interface TableMessageData extends BaseMessage {
+  type: 'table'
+  headers: string[]
+  rows: string[][]
+  title?: string
+}
+
+export type MessageData =
+  | LogMessageData
+  | FileMessageData
+  | DiffMessageData
+  | FileErrorMessageData
+  | LoadingMessageData
+  | ProgressMessageData
+  | GroupMessageData
+  | TableMessageData
+
+// ============================================
+// Logger Handle Types
+// ============================================
+
+export interface PromiseOptions<T> {
+  loading: string
+  success: string | ((data: T) => string)
+  error: string | ((error: Error) => string)
+}
+
+export interface LoadingHandle {
+  success: (message: string) => void
+  fail: (message: string) => void
+}
+
+export interface ProgressHandle {
+  update: (current: number, label?: string) => void
+  complete: (message?: string) => void
+  fail: (message?: string) => void
+}

package/src/types/prompt.types.ts

@@ -0,0 +1,106 @@
+// ============================================
+// Prompt Data Types
+// ============================================
+
+export interface ChoiceOption {
+  label: string
+  value: string
+  /** If true, this option allows text input */
+  input?: boolean
+}
+
+export interface BasePromptData {
+  id: string
+  timestamp: Date
+  resolved: boolean
+  /** Auto-resolve timeout in ms */
+  timeout?: number
+  /** Timestamp when timeout started */
+  timeoutStarted?: number
+}
+
+export interface ChoicePromptData extends BasePromptData {
+  type: 'choice'
+  question: string
+  choices: ChoiceOption[]
+  defaultChoice: string
+  selectedIndex: number
+  inputMode: boolean
+  inputValue: string
+  resolvedValue?: string
+}
+
+export interface ConfirmPromptData extends BasePromptData {
+  type: 'confirm'
+  question: string
+  confirmText: string
+  cancelText: string
+  defaultValue: boolean
+  selectedValue: boolean
+  resolvedValue?: boolean
+}
+
+export interface InputPromptData extends BasePromptData {
+  type: 'input'
+  question: string
+  placeholder: string
+  defaultValue: string
+  value: string
+  resolvedValue?: string
+}
+
+export interface MultiChoicePromptData extends BasePromptData {
+  type: 'multiChoice'
+  question: string
+  choices: ChoiceOption[]
+  selectedIndices: Set<number>
+  focusedIndex: number
+  minSelect: number
+  maxSelect: number
+  resolvedValues?: string[]
+}
+
+export type PromptData =
+  | ChoicePromptData
+  | ConfirmPromptData
+  | InputPromptData
+  | MultiChoicePromptData
+
+// ============================================
+// Prompt Options Types
+// ============================================
+
+export interface ChoiceOptions {
+  question: string
+  choices: ChoiceOption[]
+  defaultChoice?: string
+  /** Auto-resolve with default after timeout (ms) */
+  timeout?: number
+}
+
+export interface ConfirmOptions {
+  question: string
+  confirmText?: string
+  cancelText?: string
+  defaultValue?: boolean
+  /** Auto-resolve with default after timeout (ms) */
+  timeout?: number
+}
+
+export interface InputOptions {
+  question: string
+  placeholder?: string
+  defaultValue?: string
+  /** Auto-resolve with default after timeout (ms) */
+  timeout?: number
+}
+
+export interface MultiChoiceOptions {
+  question: string
+  choices: ChoiceOption[]
+  defaultChoices?: string[]
+  minSelect?: number
+  maxSelect?: number
+  /** Auto-resolve with default after timeout (ms) */
+  timeout?: number
+}

package/src/types/screen.types.ts

@@ -0,0 +1,124 @@
+import type { RGBA, SyntaxStyle, TreeSitterClient } from '@opentui/core'
+import type { ReactNode } from 'react'
+
+import type { LogLevelColorMap } from './log.types.ts'
+import type { Theme, ThemePreset } from './theme.types.ts'
+
+// ============================================
+// Screen Component Types
+// ============================================
+
+export interface ScreenProps {
+  /** Screen title/name displayed in header */
+  name: string
+
+  /** Child log messages/file logs */
+  children: ReactNode
+
+  /** Enable auto-scroll to bottom on new content */
+  stickyScroll?: boolean
+
+  /** Show scroll position indicator */
+  showScrollIndicator?: boolean
+
+  /** Screen header background color */
+  headerBackgroundColor?: string | RGBA
+
+  /** Screen header text color */
+  headerTextColor?: string | RGBA
+
+  /** Whether this screen is currently focused */
+  focused?: boolean
+
+  /** Callback when screen is scrolled */
+  onScroll?: (scrollTop: number, scrollHeight: number) => void
+}
+
+// ============================================
+// ScreenManager Component Types
+// ============================================
+
+export interface ScreenDefinition {
+  /** Unique screen identifier */
+  id: string
+
+  /** Display name for sidebar */
+  name: string
+
+  /** Optional icon/badge character */
+  icon?: string
+
+  /** Unread/notification count */
+  badgeCount?: number
+}
+
+export interface ScreenManagerProps {
+  /** Screen definitions for the sidebar */
+  screens: ScreenDefinition[]
+
+  /** Currently active screen ID */
+  activeScreenId: string
+
+  /** Callback when screen selection changes */
+  onScreenChange?: (screenId: string) => void
+
+  /** Screen content - should be conditionally rendered based on activeScreenId */
+  children: ReactNode
+
+  /** Force show/hide sidebar (overrides auto behavior) */
+  sidebarVisible?: boolean
+
+  /** Callback when sidebar visibility changes */
+  onSidebarVisibilityChange?: (visible: boolean) => void
+
+  /** Sidebar width (columns) */
+  sidebarWidth?: number
+
+  /** Sidebar position */
+  sidebarPosition?: 'left' | 'right'
+
+  /** Key to toggle sidebar visibility */
+  toggleSidebarKey?: string
+
+  /** Sidebar header title */
+  sidebarTitle?: string
+}
+
+export type FocusArea = 'sidebar' | 'content'
+
+// ============================================
+// Context Types
+// ============================================
+
+export interface LoggerContextValue {
+  /** Shared SyntaxStyle instance for code highlighting */
+  syntaxStyle?: SyntaxStyle
+
+  /** Shared TreeSitterClient for parsing */
+  treeSitterClient?: TreeSitterClient
+
+  /** Default colors for log levels (derived from theme for backwards compatibility) */
+  levelColors: LogLevelColorMap
+
+  /** Current theme */
+  theme: Theme
+}
+
+// ============================================
+// Screen Service Types
+// ============================================
+
+export type ScreenStatus = 'waiting' | 'pending' | 'success' | 'fail'
+
+export interface BindOptions {
+  exitOnCtrlC?: boolean
+  sidebarWidth?: number
+  sidebarPosition?: 'left' | 'right'
+  sidebarTitle?: string
+  /** Auto close after all screens complete successfully (delay in ms, default 5000) */
+  autoClose?: boolean | number
+  /** Theme to use for the TUI (theme object or preset name) */
+  theme?: Theme | ThemePreset
+  /** Enable mouse support (default: false) */
+  useMouse?: boolean
+}