# Fusabi TUI Examples

This directory contains example F# scripts demonstrating the Fusabi TUI bindings.

## Running Examples

To run these examples, you need to:

1. Set up a Rust application with Fusabi and fusabi-tui
2. Register the TUI bindings with the Fusabi engine
3. Execute the F# script

### Basic Setup (Rust)

```rust
use fusabi::{Engine, run_file};
use fusabi_tui::bindings::FusabiTuiModule;

fn main() -> anyhow::Result<()> {
    let mut engine = Engine::new();

    // Register TUI bindings
    let module = FusabiTuiModule::new();
    module.register(&mut engine)?;

    // Run F# script
    run_file("examples/fusabi_demo.fsx")?;

    Ok(())
}
```

## Available Examples

### fusabi_demo.fsx

Comprehensive demonstration of all Fusabi TUI bindings features:

- **Formatting Functions**
  - Number formatting (K/M/B suffixes)
  - Byte size formatting (KB/MB/GB)
  - Latency formatting (μs/ms/s)
  - Duration formatting (s/m/h)

- **Table Specification Building**
  - Creating table specifications
  - Adding columns with custom widths
  - Adding data rows
  - Setting table titles

- **Practical Examples**
  - GPU metrics table
  - Performance metrics with formatted values
  - System resource monitor

### Running fusabi_demo.fsx

```bash
# From a Rust binary that sets up the bindings
cargo run --example fusabi_demo

# Or using fusabi CLI (if available)
fusabi run examples/fusabi_demo.fsx
```

## Expected Output

The demo script produces formatted output showing:

1. Formatted numbers, bytes, latencies, and durations
2. Table specification creation steps
3. Practical use case examples

Example output:

```
=== Fusabi TUI Formatting Demo ===

--- Number Formatting ---
Small: 999
Thousands: 1.50K
Millions: 2.50M
Billions: 3.50B

--- Byte Formatting ---
Bytes: 512 B
Kilobytes: 2.00 KB
Megabytes: 5.00 MB
Gigabytes: 3.00 GB

...
```

## Understanding the Output

Note that the demo creates **widget specifications**, not rendered widgets. The output shows:

- Formatted strings from formatting functions
- Confirmation messages about table spec creation
- Metadata about the specifications built

To actually **render** these specifications as terminal UI widgets, you need to:

1. Serialize the specifications to JSON
2. Pass them to Rust code
3. Use `fusabi-tui` to interpret and render them with Ratatui

## Limitations

Due to Fusabi's current `Rc<RefCell<T>>` design (not Send+Sync):

- F# scripts **build specifications** (data structures)
- Rust code **interprets and renders** widgets
- F# scripts **cannot** directly manage widget lifecycles

This is a temporary limitation. See [FUSABI_BINDINGS.md](../docs/FUSABI_BINDINGS.md#limitations) for details.

## Creating Your Own Examples

### Template Structure

```fsharp
// 1. Import/setup (if needed in your environment)

// 2. Use formatting functions
let formattedValue = tui_format_number 1000000L

// 3. Build table specifications
let table = tui_table_spec_new ()
let table = tui_table_set_title table "My Table"
let table = tui_table_add_column table "Header1" 50L
let table = tui_table_add_row table ["Data1"]

// 4. Output or serialize as needed
printfn "%s" formattedValue
```

### Best Practices

1. **Use formatting functions for all human-readable output**
   ```fsharp
   // Good
   tui_format_bytes memoryUsage

   // Avoid
   sprintf "%d bytes" memoryUsage
   ```

2. **Build specifications incrementally**
   ```fsharp
   let table =
       tui_table_spec_new ()
       |> fun t -> tui_table_add_column t "Col1" 50L
       |> fun t -> tui_table_add_column t "Col2" 50L
   ```

3. **Separate data processing from UI building**
   ```fsharp
   // Process data first
   let metrics = calculateMetrics rawData

   // Then build UI
   let table = buildTableFromMetrics metrics
   ```

## Troubleshooting

### "Function not found" errors

Make sure the Rust code registers the TUI module before running scripts:

```rust
let module = FusabiTuiModule::new();
module.register(&mut engine)?;  // Must be called!
```

### Type errors

Ensure you're using the correct types:

```fsharp
// Correct
tui_format_number 1000L  // int64

// Wrong
tui_format_number 1000   // int32 may cause issues
```

## Further Reading

- [FUSABI_BINDINGS.md](../docs/FUSABI_BINDINGS.md) - Complete API documentation
- [Fusabi Documentation](https://github.com/fusabi-lang/fusabi)
- [Ratatui Documentation](https://ratatui.rs)

## Contributing

To add new examples:

1. Create a new `.fsx` file in this directory
2. Follow the template structure above
3. Add documentation in this README
4. Test with actual Fusabi runtime

## License

MIT OR Apache-2.0
