# XBot Form

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Windows](https://img.shields.io/badge/platform-Windows-lightgrey.svg)](https://www.microsoft.com/windows)

Windows-only Python SDK for rendering JSON Schema forms in WebView2.

## Features

- 🎨 **JSON Schema Forms** - Render dynamic forms from JSON Schema definitions
- 🖥️ **Native Windows UI** - Uses WebView2 for modern, native-feeling interfaces
- 🎯 **Type-Safe API** - Configuration classes with IDE autocompletion support
- 🔗 **Fluent Builder** - Chainable API for easy form configuration
- 🌙 **Theme Support** - Light and dark mode themes
- 🪟 **Frameless Windows** - Optional borderless windows with rounded corners

## Installation

```bash
pip install xbot-form
```

**Requirements:**
- Windows 10/11
- Python 3.8+
- WebView2 Runtime (usually pre-installed on Windows 10/11)

## Quick Start

### Basic Usage

```python
from xbot_form import show_form

# Window title is automatically extracted from schema["title"]
schema = {
    "type": "object",
    "title": "User Registration",  # <- This becomes the window title
    "properties": {
        "name": {"type": "string", "title": "Name"},
        "email": {"type": "string", "title": "Email", "format": "email"},
    },
    "required": ["name", "email"]
}

result = show_form(schema=schema)
print(f"User submitted: {result}")

# Or override with explicit title parameter
result = show_form(schema=schema, title="Custom Window Title")
```

### Builder Pattern (Recommended)

```python
from xbot_form import form_builder, FormCancelledError

try:
    result = (
        form_builder()
        .schema({
            "type": "object",
            "properties": {
                "username": {"type": "string", "title": "Username"},
                "password": {"type": "string", "title": "Password"},
            }
        })
        .ui_schema({
            "password": {"ui:widget": "password"}
        })
        .title("Login")
        .size(600, 400)
        .frameless(corner_radius=16)
        .theme("dark")
        .show()
    )
    print(f"Login: {result}")
except FormCancelledError:
    print("Login cancelled")
```

### Configuration Classes

```python
from xbot_form import (
    show_form_with_config,
    FormConfig,
    WindowOptions,
    DisplayOptions,
    FormCancelledError
)

config = FormConfig(
    schema={
        "type": "object",
        "properties": {
            "task": {"type": "string", "title": "Task Name"},
            "priority": {
                "type": "string",
                "title": "Priority",
                "enum": ["Low", "Medium", "High"]
            }
        }
    },
    window=WindowOptions(
        width=800,
        height=600,
        title="New Task",
        frameless=True,
        corner_radius=12
    ),
    display=DisplayOptions(
        theme="light",
        debug=False
    )
)

try:
    result = show_form_with_config(config)
    print(f"Task created: {result}")
except FormCancelledError:
    print("Cancelled")
```

## API Reference

### Functions

| Function                        | Description                                   |
| ------------------------------- | --------------------------------------------- |
| `show_form(...)`                | Display a form with individual parameters     |
| `show_form_with_config(config)` | Display a form using FormConfig object        |
| `form_builder()`                | Create a FormBuilder for fluent configuration |

### Configuration Classes

| Class            | Description                            |
| ---------------- | -------------------------------------- |
| `FormConfig`     | Complete form configuration            |
| `FormSchema`     | JSON Schema with optional UI schema    |
| `WindowOptions`  | Window size, title, frameless settings |
| `DisplayOptions` | Theme, debug mode, locale settings     |
| `FormBuilder`    | Fluent builder for form configuration  |

### Exceptions

| Exception                  | Description                       |
| -------------------------- | --------------------------------- |
| `XBotFormError`            | Base exception for all SDK errors |
| `FormCancelledError`       | User cancelled or closed the form |
| `FormTimeoutError`         | Form display timed out            |
| `WebViewError`             | WebView2 initialization error     |
| `WebViewNotAvailableError` | WebView2 runtime not installed    |
| `WindowError`              | Window creation error             |

## Parameters

### show_form()

| Parameter       | Type   | Default   | Description                                                      |
| --------------- | ------ | --------- | ---------------------------------------------------------------- |
| `schema`        | `dict` | `None`    | JSON Schema for the form (supports `title` for window title)     |
| `title`         | `str`  | `None`    | Window title. Priority: `title` > `schema["title"]` > "应用配置" |
| `width`         | `int`  | `1000`    | Window width in pixels                                           |
| `height`        | `int`  | `800`     | Window height in pixels                                          |
| `frameless`     | `bool` | `True`    | Borderless window mode                                           |
| `corner_radius` | `int`  | `32`      | Corner radius for frameless windows                              |
| `debug`         | `bool` | `False`   | Enable DevTools                                                  |
| `theme`         | `str`  | `"light"` | Color theme (`"light"` or `"dark"`)                              |

## License

MIT License - see [LICENSE](LICENSE) for details.
