Metadata-Version: 2.4
Name: promptius-gui-schema
Version: 2.0.2
Summary: Type-safe UI schema definitions for cross-platform UI generation
Project-URL: Homepage, https://github.com/AgentBossMode/promptius-gui
Project-URL: Repository, https://github.com/AgentBossMode/promptius-gui
Project-URL: Documentation, https://github.com/AgentBossMode/promptius-gui#readme
Project-URL: Bug Tracker, https://github.com/AgentBossMode/promptius-gui/issues
Author-email: Kanishk Gupta <51890299+kanishkgupta2000@users.noreply.github.com>
Maintainer-email: Kanishk Gupta <51890299+kanishkgupta2000@users.noreply.github.com>
License: MIT License
        
        Copyright (c) 2024 Kanishk Gupta
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: angular,pydantic,react,schema,typescript,ui,validation,vue
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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-Python: >=3.8.1
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: datamodel-code-generator>=0.25.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: langsmith>=0.1.147; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Promptius GUI Schema

[![PyPI version](https://badge.fury.io/py/promptius-gui-schema.svg)](https://badge.fury.io/py/promptius-gui-schema)
[![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)

**Type-safe UI schema definitions for cross-platform UI generation**

Promptius GUI Schema provides robust, type-safe UI schema definitions that can be used to generate UI components across different frameworks (React, Vue, Angular, etc.) with full TypeScript compatibility.

## Features

- 🎯 **Type-Safe**: Built with Pydantic for runtime validation and type safety
- 🔄 **Cross-Platform**: Compatible with React, Vue, Angular, and other frameworks
- 📝 **TypeScript Compatible**: Full TypeScript definitions available
- 🎨 **Framework Agnostic**: Works with shadcn/ui, Material-UI, Chakra UI, Ant Design
- 🚀 **Zero Dependencies**: Only requires Pydantic (no heavy framework dependencies)
- 📦 **Lightweight**: Minimal package size for maximum performance

## Installation

```bash
pip install promptius-gui-schema
```

## Quick Start

```python
from promptius_gui_schema import UISchema, UIMetadata, ButtonComponent, ButtonProps, ButtonVariant

# Create a simple button schema
schema = UISchema(
    metadata=UIMetadata(
        title="My App",
        description="A simple application",
        framework="shadcn"
    ),
    root=ButtonComponent(
        id="submit-btn",
        props=ButtonProps(
            label="Submit",
            variant=ButtonVariant.PRIMARY
        )
    )
)

# Export as JSON for frontend consumption
json_schema = schema.to_json()
print(json_schema)
```

## Supported Components

### Layout Components
- **Container**: Responsive container with max-width and padding
- **Grid**: Flexible grid layout with configurable columns
- **Stack**: Vertical or horizontal stack layout

### Form Components
- **Button**: Interactive buttons with variants and states
- **Input**: Text inputs with validation and helper text
- **Textarea**: Multi-line text input with configurable rows

### Display Components
- **Text**: Typography with semantic tags and styling
- **Card**: Content containers with elevation and padding
- **Alert**: Notifications with different severity levels
- **Chart**: Data visualization with multiple chart types

## Framework Support

| Framework | Status | Notes |
|-----------|--------|-------|
| **shadcn/ui** | ✅ Full Support | Default framework |
| **Material-UI** | ✅ Full Support | Complete component mapping |
| **Chakra UI** | ✅ Full Support | All components supported |
| **Ant Design** | ✅ Full Support | Enterprise-ready components |

## Advanced Usage

### Event Handling

```python
from promptius_gui_schema import (
    EventType, SetStateAction, SubmitFormAction, 
    NavigateAction, EventBinding
)

# Button with click event
button = ButtonComponent(
    id="submit-btn",
    props=ButtonProps(label="Submit"),
    events=[
        (EventType.CLICK, SubmitFormAction(
            type="submitForm",
            endpoint="/api/submit",
            method="POST"
        ))
    ]
)
```

### Complex Layouts

```python
from promptius_gui_schema import (
    ContainerComponent, ContainerProps,
    GridComponent, GridProps,
    CardComponent, CardProps,
    TextComponent, TextProps, TextTag
)

# Dashboard layout
dashboard = UISchema(
    metadata=UIMetadata(title="Dashboard", framework="material-ui"),
    root=ContainerComponent(
        id="dashboard",
        props=ContainerProps(maxWidth=1200, padding=24),
        children=[
            GridComponent(
                id="metrics-grid",
                props=GridProps(columns=3, gap=16),
                children=[
                    CardComponent(
                        id="users-card",
                        props=CardProps(title="Total Users"),
                        children=[
                            TextComponent(
                                id="users-count",
                                props=TextProps(
                                    content="12,345",
                                    tag=TextTag.H2
                                )
                            )
                        ]
                    )
                ]
            )
        ]
    )
)
```

### Chart Components

```python
from promptius_gui_schema import (
    ChartComponent, ChartProps, ChartType, ChartSeries
)

# Bar chart
chart = ChartComponent(
    id="sales-chart",
    props=ChartProps(
        chartType=ChartType.BAR,
        title="Sales Data",
        series=[
            ChartSeries(name="Q1", data=[100, 200, 150]),
            ChartSeries(name="Q2", data=[120, 180, 200])
        ],
        labels=["Jan", "Feb", "Mar"]
    )
)
```

## TypeScript Integration

The package is designed to work seamlessly with TypeScript. The corresponding TypeScript definitions are available in the main Promptius GUI repository:

```typescript
import { UISchema, ButtonComponent, ButtonProps } from '@promptius-gui/schemas';

const schema: UISchema = {
  metadata: {
    title: "My App",
    framework: "shadcn"
  },
  root: {
    type: "button",
    id: "submit-btn",
    props: {
      label: "Submit",
      variant: "primary"
    }
  }
};
```

## Validation

All schemas are validated at runtime using Pydantic:

```python
from promptius_gui_schema import UISchema, UIMetadata, ButtonComponent, ButtonProps

try:
    # This will raise a validation error
    invalid_schema = UISchema(
        metadata=UIMetadata(title=""),  # Empty title not allowed
        root=ButtonComponent(
            id="btn",
            props=ButtonProps(label="")  # Empty label not allowed
        )
    )
except ValidationError as e:
    print(f"Validation failed: {e}")
```

## Development

### Installation for Development

```bash
git clone https://github.com/AgentBossMode/promptius-gui.git
cd promptius-gui/python
pip install -e .
```

### Running Tests

```bash
pip install -e ".[dev]"
pytest
```

### Code Formatting

```bash
black promptius_gui_schema/
isort promptius_gui_schema/
```

## API Reference

### Core Classes

- **`UISchema`**: Top-level schema container
- **`UIMetadata`**: Schema metadata and framework information
- **`UIComponent`**: Union type for all component types

### Component Types

- **Layout**: `ContainerComponent`, `GridComponent`, `StackComponent`
- **Form**: `ButtonComponent`, `InputComponent`, `TextareaComponent`
- **Display**: `TextComponent`, `CardComponent`, `AlertComponent`, `ChartComponent`

### Event System

- **Event Types**: `EventType` enum (CLICK, SUBMIT, CHANGE, etc.)
- **Actions**: `NavigateAction`, `SetStateAction`, `SubmitFormAction`, etc.
- **Binding**: Tuple format `(EventType, EventAction)` for TypeScript compatibility

## Contributing

Contributions are welcome! Please read our [Contributing Guide](https://github.com/AgentBossMode/promptius-gui/blob/main/CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Related Projects

- [Promptius GUI Core](https://github.com/AgentBossMode/promptius-gui) - Main Promptius GUI repository
- [Promptius GUI React](https://github.com/AgentBossMode/promptius-gui/tree/main/js/packages/core) - React renderer
- [Promptius GUI Vue](https://github.com/AgentBossMode/promptius-gui) - Vue renderer (coming soon)

## Support

- 📖 [Documentation](https://github.com/AgentBossMode/promptius-gui#readme)
- 🐛 [Issue Tracker](https://github.com/AgentBossMode/promptius-gui/issues)
- 💬 [Discussions](https://github.com/AgentBossMode/promptius-gui/discussions)
