@bobfrankston/cmsgbox/README.md

Cross-platform dialog utility for Node.js using Python and tkinter

# @bobfrankston/cmsgbox

Cross-platform dialog utility for Node.js using Python and tkinter with TypeScript support.

## Features

- **Cross-platform**: Works on Windows, Linux, and macOS
- **Professional dialogs**: Custom tkinter implementations with better UX
- **Automatic fallbacks**: Gracefully degrades to command-line input if GUI unavailable
- **Self-healing**: Automatically installs missing tkinter dependencies
- **TypeScript support**: Full type definitions and modern async/await API
- **RMFC compatible**: Drop-in replacement for existing RMFC usage

## Installation

```bash
npm install @bobfrankston/cmsgbox
```

## Quick Start

```typescript
import { showMessage, showInput } from '@bobfrankston/cmsgbox';

// Simple message dialog
await showMessage("Hello World", "Greeting");

// Input dialog with default value
const name = await showInput("Enter your name:", "Input", "John Doe");
if (name) {
  console.log(`Hello, ${name}!`);
}
```

## API

### showMessage(message, title?)
Displays a message dialog with OK/Cancel buttons.

### showInput(message, title?, defaultText?)
Displays an input dialog and returns the user's input or undefined if canceled.

### MessageBox class
Object-oriented API for dialog management.

### messageBox(options)
Unified function using options object:

```typescript
const result = await messageBox({
    message: "Enter your name:",
    title: "Input Dialog",
    input: true,
    defaultText: "John Doe"
});
```

## Architecture

This package uses Python and tkinter for cross-platform dialog display:

- **Windows**: Custom tkinter dialogs with native Windows look
- **Linux**: Custom tkinter dialogs with native Linux theming
- **macOS**: Custom tkinter dialogs with native macOS styling
- **Fallback**: Command-line input when GUI unavailable

## Compatibility

- **Node.js**: >= 22.0.0
- **Python**: 3.x (auto-detected, falls back to python3 then python)
- **tkinter**: Auto-installed if missing

## Building

```bash
npm run build
```

## Testing

```bash
npm test
```

## Migration from RMFC

This package is fully compatible with RMFC command-line interface:

```bash
# RMFC style (still works)
python pyutils/msgbox.py -input -title "Name" "Enter your name:"

# Enhanced JSON style (recommended)
python pyutils/msgbox.py -json '{"type": "input", "title": "Name", "message": "Enter your name:"}'
```

## License

MIT