Metadata-Version: 2.3
Name: xbot-form
Version: 0.2.1
Summary: Windows-only Python SDK for rendering JSON Schema forms in WebView2
License: MIT
Keywords: webview,form,json-schema,windows,gui,rpa
Author: XBot Team
Requires-Python: >=3.7,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Typing :: Typed
Requires-Dist: comtypes (>=1.2.0,<2.0.0)
Requires-Dist: pywin32 (>=306)
Project-URL: Bug Tracker, https://github.com/xbot/xbot-form/issues
Project-URL: Documentation, https://github.com/xbot/xbot-form#readme
Description-Content-Type: text/markdown

# 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, FormCancelledError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "title": "Name"},
        "email": {"type": "string", "title": "Email", "format": "email"},
    },
    "required": ["name", "email"]
}

try:
    result = show_form(schema=schema, title="User Registration")
    print(f"User submitted: {result}")
except FormCancelledError:
    print("User cancelled the form")
```

### 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            |
| `title`         | `str`  | `None`    | Window title                        |
| `width`         | `int`  | `1000`    | Window width in pixels              |
| `height`        | `int`  | `800`     | Window height in pixels             |
| `frameless`     | `bool` | `False`   | Borderless window mode              |
| `corner_radius` | `int`  | `0`       | 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.

