488 lines
13 KiB
Markdown
488 lines
13 KiB
Markdown
# 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
|