## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require pdphilip/omniterm

Add Trait to Command:

use OmniTerm\HasOmniTerm;

class MyCommand extends Command {
    use HasOmniTerm;
}

First Use Case:

public function handle() {
    $this->omni->success('Task completed'); // Green status badge
}

Where to Look First

Built-in Components: Check the Built-in Components section for ready-to-use UI elements.
Samples: Run php artisan omniterm:full-demo to see all features in action.
Tailwind Classes: Refer to the Supported Classes table for styling options.

Implementation Patterns

Common Workflows

1. Status Messages

// Simple status
$this->omni->success('Migration complete');

// Detailed status block
$this->omni->statusSuccess(
    'Migration Complete',
    'All 42 records processed',
    ['Run cache:clear']
);

2. Progress Bars

// Simple progress bar
$bar = $this->omni->progressBar(100)->steps();
$bar->start();

// Update progress
foreach ($items as $item) {
    $bar->advance();
}
$bar->finish();

3. Live Tasks with Counters

$task = $this->omni->liveTask('Processing records', spinner: Spinner::Dots3)
    ->row('Created', 0, 'text-sky-500')
    ->row('Failed', 0, 'text-rose-500');

for ($i = 0; $i < 5; $i++) {
    $result = $task->run(function () {
        return ['created' => rand(1, 10), 'failed' => rand(0, 2)];
    });
    $task->increment('Created', $result['created']);
    $task->increment('Failed', $result['failed']);
}
$task->finish('Done');

4. Interactive Browser

$selected = $this->omni->browse('Servers', [
    'web-01' => function ($omni) {
        $omni->statusSuccess('Healthy', 'All checks passing');
    },
    'db-01' => ['status' => 'running', 'cpu' => '45%'],
]);

5. Custom HTML Rendering

$this->omni->render(<<<HTML
<div class="flex">
    <span class="bg-emerald-600 text-white px-2">PASS</span>
    <span class="text-zinc-400 flex-1">Database connection verified</span>
</div>
HTML
);

Integration Tips

Blade Templates

Store reusable UI in resources/views/cli/:

// resources/views/cli/status.blade.php
<div class="flex">
    <span class="bg-{{ $color }}-600 text-white px-2">{{ $badge }}</span>
    <span class="text-zinc-400 flex-1">{{ $message }}</span>
</div>

// In command
$this->omni->view('cli.status', [
    'badge' => 'OK',
    'color' => 'emerald',
    'message' => 'System ready',
]);

Async Operations

Use runTask() for background processing:

$result = $this->omni->runTask('Processing...', function () {
    return ['data' => 'processed'];
}, Spinner::Sand);

Terminal Dimensions

$width = $this->omni->terminal()->getWidth();
if ($width < 80) {
    $this->omni->render('<div class="text-sm">Narrow terminal detected</div>');
}

Gotchas and Tips

Pitfalls

Color Fallback:
- Older terminals (e.g., macOS Terminal) may not support truecolor.
- Fix: Use text-{color}-{shade} (e.g., text-sky-500) instead of arbitrary RGB (text-[0,191,255]) for broader compatibility.
Live Views:
- Forgetting to call $this->omni->endLiveView() can leave stale output.
- Tip: Use a finally block or wrap in a try-catch:
```
try {
    $live = $this->omni->liveView('...');
    // ... updates
} finally {
    $this->omni->endLiveView();
}
```
Progress Bar Stuck:
- If $bar->finish() is omitted, the bar remains indeterminate.
- Fix: Always call finish() or stop():
```
$bar->stop(); // For manual control
```
Spinner Not Showing:
- Ensure the terminal supports Unicode (most modern terminals do).
- Fallback: Use Spinner::Dots (ASCII-only).
Blade Caching:
- Clear views after adding new Blade templates:
```
php artisan view:clear
```

Debugging Tips

Check ANSI Output:

Use parse() to inspect raw ANSI without printing:

$ansi = $this->omni->parse('<span class="text-red-500">Test</span>');
$this->line($ansi); // Log to terminal

Terminal Detection:
- Force 256-color mode for testing:
```
$this->omni->terminal()->force256Colors();
```
Gradient Issues:
- Gradients may appear blocky in 256-color mode.
- Tip: Use fewer via-{color} steps or switch to bg-{color}-{shade}.

Extension Points

Custom Spinners:
- Extend the Spinner enum or create a new animation class by implementing OmniTerm\Contracts\Spinner.

New Components:

Build reusable components by combining render() and Blade templates.

Example: Create a Card component:

$this->omni->render(<<<HTML
<div class="border border-zinc-600 rounded-lg p-2">
    <div class="font-bold">{{ $title }}</div>
    <div>{!! $content !!}</div>
</div>
HTML
);

Dynamic Styling:

Use PHP variables in HTML:

$status = 'error';
$this->omni->render("<span class='text-$status-500'>$status</span>");

Event Listeners:
- Hook into OmniTerm’s rendering lifecycle by extending the OmniTerm class and overriding methods like compile().
Configuration:
- Override defaults (e.g., spinner speed) by publishing the config:
```
php artisan vendor:publish --provider="OmniTerm\OmniTermServiceProvider"
```
- Modify config/omniterm.php (e.g., set default_spinner to Spinner::Clock).

Performance Tips

Batch Rendering:

Combine multiple render() calls into one for complex UIs:

$this->omni->render(<<<HTML
<div>{$this->omni->statusSuccess('Ready')}</div>
<div>{$this->omni->tableHeader('Metrics')}</div>
HTML
);

Avoid Live Views for Simple Updates:

Use render() + \r (carriage return) for lightweight updates:

for ($i = 0; $i <= 100; $i++) {
    $this->output->write("\rProgress: {$i}%");
    usleep(50000);
}
$this->output->writeln();

Reuse Parsed ANSI:

Cache parsed ANSI strings for repeated use:

$header = $this->omni->parse('<div class="font-bold">Header</div>');
$this->line($header);

Terminal-Specific Quirks

Terminal	Known Issue	Workaround
macOS Terminal	Limited truecolor support	Use `text-{color}-{shade}`
Windows CMD	No Unicode support	Use `Spinner::Dots` (ASCII)
WezTerm	May ignore some ANSI sequences	Test with `this->omni->parse()`
Alacritty	Gradients may render unevenly	Reduce `via-{color}` steps

Advanced Usage

Nested Components:
- Combine components dynamically:
```
$this->omni->render(<<<HTML
```

Omniterm Laravel Package