smartlog/readme.plan.md

# Smartlog Interactive Console Features Plan

## Overview

This document outlines the plan for enhancing the console output capabilities of `@push.rocks/smartlog` by creating a comprehensive interactive console module. This involves renaming the current `ts_source_ora` module to `ts_source_interactive`, implementing our own spinner functionality (removing the ora dependency), and adding new features like progress bars and other interactive elements.

## Implementation Steps

### 1. Rename and Restructure

- Rename directory from `ts_source_ora` to `ts_source_interactive`
- Update all imports, exports, and references
- Update package.json exports to reflect new module name
- Maintain backward compatibility through proper export paths

### 2. Custom Spinner Implementation

- Create a native spinner implementation to replace ora dependency
- Implement spinner frames and animation timing
- Maintain API compatibility with current spinner methods:
  - `text(textArg)` - Set text and start spinner
  - `stop()` - Stop the spinner
  - `finishSuccess(textArg?)` - Mark as succeeded
  - `finishFail(textArg?)` - Mark as failed
  - `successAndNext(textArg)` - Success and start new spinner
  - `failAndNext(textArg)` - Fail and start new spinner
- Add spinner customization options (speed, frames, colors)

### 3. Progress Bar Implementation

- Create a progress bar component with the following features:
  - Configurable width and style
  - Percentage display
  - ETA calculation
  - Current/total value display
  - Custom formatting
  - Theming support
  - Methods for incrementing and updating

### 4. Additional Interactive Features

- Add indeterminate progress indicator
- Add multi-line status display
- Add table formatting for structured data
- Add interactive prompts/confirmations

### 5. Testing

- Update existing tests to work with new implementation
- Add tests for new progress bar functionality
- Add tests for additional interactive features
- Ensure consistent behavior across platforms

### 6. Documentation

- Update README with examples of new features
- Add API documentation for all new methods
- Include usage examples

## Implementation Details

### Progress Bar API

```typescript
// Creating a progress bar
const progressBar = new SmartlogProgressBar({
  total: 100,
  width: 40,
  complete: '=',
  incomplete: ' ',
  renderThrottle: 100, // ms
  clearOnComplete: false,
  showEta: true
});

// Updating a progress bar
progressBar.update(50); // Update to 50%
progressBar.increment(10); // Increment by 10
progressBar.complete(); // Mark as complete
```

### Spinner API (maintains compatibility)

```typescript
// Current API (to be maintained)
const spinner = new SmartlogSourceInteractive();
spinner.text('Loading data');
spinner.finishSuccess('Data loaded successfully');

// New additions
spinner.setSpinnerStyle('dots'); // Change spinner style
spinner.setColor('green'); // Change color
```

## Benefits

- Remove external dependency (ora) for better control and smaller bundle size
- Provide more interactive console features for improved user experience
- Maintain consistent API styling across all smartlog modules
- Improve testability with custom implementation
- Enable more advanced terminal interactions