# Terminal User Interface (TUI) Guide

## Overview

The Shopify Price Updater includes a modern Terminal User Interface (TUI) built with Ink (React for CLI) that provides an interactive, user-friendly way to manage price updates. The TUI is optimized for cross-platform compatibility, with special attention to Windows terminal environments.

## Getting Started

### Launch the TUI

```bash
npm run tui
```

### System Requirements

- Node.js 16 or higher
- Modern terminal with Unicode support
- Recommended terminals:
  - **Windows**: Windows Terminal, PowerShell 7+
  - **macOS**: iTerm2, Terminal.app
  - **Linux**: GNOME Terminal, Konsole, Alacritty

## Interface Overview

### Main Menu

The main menu serves as the central navigation hub:

```
┌─ Shopify Price Updater ─────────────────────────┐
│                                                 │
│  ► Configuration                            [C] │
│    Operations                               [O] │
│    Scheduling                               [S] │
│    View Logs                                [L] │
│    Tag Analysis                             [T] │
│    Exit                                     [Q] │
│                                                 │
└─────────────────────────────────────────────────┘
```

**Navigation:**

- Use arrow keys to navigate
- Press Enter to select
- Use keyboard shortcuts (letters in brackets)
- Press 'q' or Escape to exit

### Status Bar

The status bar displays real-time information:

```
● Connected | Store: your-store.myshopify.com | Progress: 45%
```

**Indicators:**

- **● Connected**: API connection status (green = connected, red = disconnected)
- **Store**: Current Shopify store domain
- **Progress**: Current operation progress percentage

## Screen Components

### Configuration Screen

Interactive form for managing environment settings:

```
┌─ Configuration ─────────────────────────────────┐
│                                                 │
│  Shopify Domain: [your-store.myshopify.com   ] │
│  Access Token:   [shpat_*********************] │
│  Target Tag:     [sale                       ] │
│  Price Adjust:   [10                         ]% │
│  Operation Mode: ► Update                       │
│                    Rollback                     │
│                                                 │
│  [Test Connection] [Save] [Cancel]              │
│                                                 │
└─────────────────────────────────────────────────┘
```

**Features:**

- Real-time input validation
- Secure token display (masked)
- Connection testing
- Configuration persistence

### Operation Screen

Live progress tracking during price updates:

```
┌─ Price Update Operation ────────────────────────┐
│                                                 │
│  Target Tag: sale                               │
│  Operation: Update prices by +10%              │
│                                                 │
│  Progress: ████████████░░░░░░░░ 60% (15/25)     │
│                                                 │
│  Current Product: "Awesome T-Shirt"            │
│  Price: $19.99 → $21.99                        │
│                                                 │
│  ✅ Completed: 14                               │
│  ⚠️  Skipped: 1                                 │
│  ❌ Errors: 0                                   │
│                                                 │
└─────────────────────────────────────────────────┘
```

**Features:**

- Real-time progress visualization
- Current product information
- Success/error counters
- Detailed operation status

### Scheduling Screen

Date/time picker for automated operations:

```
┌─ Schedule Operation ────────────────────────────┐
│                                                 │
│  Operation Type: ► Price Update                 │
│                    Price Rollback               │
│                                                 │
│  Schedule Date: [2024-12-25]                    │
│  Schedule Time: [10:30:00]                      │
│  Timezone:      [EST (-05:00)]                  │
│                                                 │
│  Countdown: 2 days, 14 hours, 23 minutes       │
│                                                 │
│  [Schedule] [Cancel Schedule] [Back]            │
│                                                 │
└─────────────────────────────────────────────────┘
```

**Features:**

- Date/time picker interface
- Timezone selection
- Live countdown display
- Schedule management

### Log Viewer Screen

Paginated log display with search capabilities:

```
┌─ Log Viewer ────────────────────────────────────┐
│                                                 │
│  Search: [error                              ] 🔍│
│                                                 │
│  2024-01-15 10:30:15 | INFO  | Operation start │
│  2024-01-15 10:30:16 | INFO  | Found 25 prods  │
│  2024-01-15 10:30:17 | ERROR | API rate limit  │
│  2024-01-15 10:30:20 | INFO  | Retrying...     │
│  2024-01-15 10:30:21 | INFO  | Update success  │
│                                                 │
│  Page 1 of 5 | Showing 5 of 23 entries         │
│  [Previous] [Next] [Export] [Clear] [Back]     │
│                                                 │
└─────────────────────────────────────────────────┘
```

**Features:**

- Real-time search and filtering
- Pagination for large log files
- Log level filtering (INFO, WARN, ERROR)
- Export functionality

### Tag Analysis Screen

Product tag statistics and recommendations:

```
┌─ Tag Analysis ──────────────────────────────────┐
│                                                 │
│  Available Tags:                                │
│                                                 │
│  ► sale          (25 products)                  │
│    clearance     (12 products)                  │
│    seasonal      (8 products)                   │
│    new-arrival   (15 products)                  │
│    featured      (6 products)                   │
│                                                 │
│  Sample Products for "sale":                    │
│  • Awesome T-Shirt ($19.99)                    │
│  • Cool Hoodie ($39.99)                        │
│  • Nice Jeans ($49.99)                         │
│                                                 │
│  [Analyze] [Refresh] [Back]                     │
│                                                 │
└─────────────────────────────────────────────────┘
```

**Features:**

- Tag statistics and product counts
- Sample product display
- Tag recommendations
- Real-time analysis

## Component Architecture

### Core Components

#### TuiApplication

Main application component that orchestrates the entire interface:

```jsx
const TuiApplication = () => {
	return (
		<AppProvider>
			<Box flexDirection="column" height="100%">
				<StatusBar />
				<Router />
			</Box>
		</AppProvider>
	);
};
```

#### AppProvider

State management using React Context:

```jsx
const AppProvider = ({ children }) => {
	const [appState, setAppState] = useState({
		currentScreen: "main-menu",
		configuration: {},
		operationState: null,
	});

	return (
		<AppContext.Provider value={{ appState, setAppState }}>
			{children}
		</AppContext.Provider>
	);
};
```

### Reusable Components

#### ProgressBar

Visual progress indicator with customizable styling:

```jsx
<ProgressBar progress={60} label="Processing products" color="blue" />
```

#### InputField

Form input with validation:

```jsx
<InputField
	label="Target Tag"
	value={tag}
	onChange={setTag}
	validation={validateTag}
	placeholder="Enter product tag"
/>
```

#### MenuList

Keyboard-navigable menu:

```jsx
<MenuList
	items={menuItems}
	selectedIndex={selectedIndex}
	onSelect={handleSelect}
/>
```

### Custom Hooks

#### useAppState

Access and modify application state:

```jsx
const { appState, setAppState } = useAppState();
```

#### useNavigation

Handle screen navigation:

```jsx
const { navigateTo, goBack } = useNavigation();
```

#### useServices

Access service layer:

```jsx
const { shopifyService, productService } = useServices();
```

## Windows Compatibility

### Optimizations

The TUI includes specific optimizations for Windows environments:

- **Unicode Support**: Enhanced character rendering for Windows terminals
- **Color Compatibility**: Fallback color schemes for older terminals
- **Keyboard Handling**: Windows-specific key event processing
- **Performance**: Optimized rendering for Windows Terminal

### Supported Windows Terminals

- **Windows Terminal** (recommended): Full feature support
- **PowerShell 7+**: Good compatibility with modern features
- **Command Prompt**: Basic functionality with graceful degradation
- **PowerShell 5.1**: Limited color support, core features work

### Troubleshooting Windows Issues

#### Unicode Characters Not Displaying

```bash
# Set console to UTF-8
chcp 65001
npm run tui
```

#### Colors Not Working

The TUI automatically detects color support and falls back to monochrome when needed.

#### Keyboard Issues

Ensure your terminal supports modern key sequences. Windows Terminal provides the best experience.

## Performance Features

### Memory Management

- **Component Memoization**: React.memo for expensive components
- **Virtual Scrolling**: Efficient handling of large lists
- **Cleanup**: Automatic cleanup of event listeners and timers
- **Memory Monitoring**: Built-in memory usage tracking

### Rendering Optimization

- **Debounced Updates**: Prevents excessive re-renders
- **Selective Updates**: Only updates changed components
- **Efficient State**: Optimized state structure for performance

## Accessibility

### Screen Reader Support

- Semantic component structure
- ARIA labels and descriptions
- Keyboard-only navigation
- Clear focus indicators

### High Contrast Mode

- Automatic detection of system preferences
- Enhanced color contrast ratios
- Alternative visual indicators

### Keyboard Navigation

All functionality is accessible via keyboard:

- **Tab/Shift+Tab**: Navigate between elements
- **Arrow Keys**: Navigate lists and menus
- **Enter/Space**: Activate buttons and selections
- **Escape**: Cancel or go back
- **Ctrl+C**: Exit application

## Development Patterns

### Component Structure

```jsx
const MyComponent = ({ prop1, prop2 }) => {
	const [state, setState] = useState(initialState);
	const { appState } = useAppState();

	useEffect(() => {
		// Setup and cleanup
		return () => {
			// Cleanup
		};
	}, []);

	return <Box>{/* Component JSX */}</Box>;
};
```

### Error Handling

```jsx
const ErrorBoundary = ({ children }) => {
	const [error, setError] = useState(null);

	if (error) {
		return (
			<Box borderStyle="single" borderColor="red">
				<Text color="red">Error: {error.message}</Text>
				<Text>Press 'r' to retry or 'q' to quit</Text>
			</Box>
		);
	}

	return children;
};
```

### Testing Components

```jsx
import { render } from "ink-testing-library";
import MyComponent from "../MyComponent";

test("renders correctly", () => {
	const { lastFrame } = render(<MyComponent />);
	expect(lastFrame()).toContain("Expected text");
});
```

## Best Practices

### State Management

- Use React Context for global state
- Keep component state local when possible
- Implement proper cleanup in useEffect

### Performance

- Use React.memo for expensive components
- Implement virtual scrolling for large lists
- Debounce rapid state updates

### Error Handling

- Implement error boundaries
- Provide clear error messages
- Include recovery mechanisms

### Accessibility

- Ensure keyboard navigation works
- Provide clear focus indicators
- Support screen readers

## Migration from Blessed

The TUI was migrated from Blessed to Ink for better Windows compatibility:

### Key Improvements

- **Better Windows Support**: Native Windows terminal compatibility
- **Modern Architecture**: React-based component system
- **Performance**: Reduced flickering and improved rendering
- **Maintainability**: Modern JavaScript patterns and testing

### Breaking Changes

- Component API changed from Blessed widgets to React components
- Event handling updated to React patterns
- State management moved to React Context

### Migration Benefits

- Improved cross-platform compatibility
- Better development experience
- Enhanced testing capabilities
- Modern UI patterns and components