flask-newui

Name	flask-newui JSON
Version	1.0.0 JSON
	download
home_page	None
Summary	A modern reactive frontend framework that bridges Flask/Jinja2 with modern UI capabilities
upload_time	2025-07-24 14:32:18
maintainer	None
docs_url	None
author	None
requires_python	>=3.7
license	MIT License Copyright (c) 2025 Flask-NewUI Framework Contributors 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.
keywords	flask jinja2 frontend framework reactive ui components
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # NewUI Framework

[![PyPI version](https://badge.fury.io/py/flask-newui.svg)](https://badge.fury.io/py/flask-newui)
[![Python Support](https://img.shields.io/pypi/pyversions/flask-newui.svg)](https://pypi.org/project/flask-newui/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![AI Framework Schema](https://img.shields.io/badge/AI%20Framework%20Schema-Available-brightgreen.svg)](#🤖-ai-assisted-development)

**A modern reactive frontend framework that bridges Flask/Jinja2 with modern UI capabilities**

NewUI transforms traditional Flask/Jinja2 development by adding reactive capabilities while maintaining the simplicity and server-side rendering benefits that make Flask development straightforward. Build sleek, intuitive frontends that rival modern frameworks without leaving the Flask ecosystem.

> **🤖 NEW: AI-Powered Development**  
> Flask-NewUI includes the world's first **AI Framework Schema (AFS)** - making AI tools instant experts in Flask-NewUI development. Get framework-specific code generation, smart recommendations, and expert debugging assistance. [Learn more ↓](#🤖-ai-assisted-development)

## ✨ Features

**🎯 Core Capabilities**
- **Zero Build Step**: Works without webpack or compilation
- **Progressive Enhancement**: Full functionality without JavaScript, enhanced with it
- **Flask-Native**: Seamless integration with Flask's request/response cycle
- **CSS Framework Agnostic**: Works with Tailwind, Bootstrap, or custom CSS
- **Jinja2-First**: All components leverage Jinja2's existing capabilities

**🤖 AI-Optimized Development**
- **AI Framework Schema (AFS)**: Comprehensive machine-readable documentation
- **Instant AI Expertise**: AI tools become Flask-NewUI experts immediately
- **Better Code Generation**: AI generates idiomatic Flask-NewUI code
- **Smart Recommendations**: AI knows when to use Flask-NewUI vs other solutions

**🚀 Phase 1: Foundation**
- ✅ Component macro system with parameter validation
- ✅ Automatic AJAX partial rendering
- ✅ Basic event handling (click, submit, change)
- ✅ State persistence via data attributes
- ✅ Flask extension for easy integration

**⚡ Phase 2: Enhanced Interactivity**
- ✅ Two-way data binding for forms
- ✅ Conditional rendering helpers
- ✅ List rendering with efficient updates
- ✅ Component lifecycle hooks
- ✅ Built-in loading states

**🔥 Phase 3: Advanced Features**
- ✅ WebSocket support for real-time updates
- ✅ Component composition patterns
- ✅ State stores for complex apps
- ✅ Route-based code splitting
- ✅ Development tools (debugger, component inspector)

## 🚀 Quick Start

### Installation

```bash
pip install flask-newui

# For WebSocket support
pip install flask-newui[websocket]

# For development
pip install flask-newui[dev]
```

### Basic Usage

```python
from flask import Flask, render_template_string
from newui import NewUI
from newui import components as ui

app = Flask(__name__)
newui = NewUI(app)

# Simple reactive page
@app.route('/')
def index():
    return render_template_string('''
    <!DOCTYPE html>
    <html>
    <head>
        <title>NewUI Demo</title>
        <link href="{{ url_for('newui.static', filename='newui.css') }}" rel="stylesheet">
    </head>
    <body>
        <div class="container">
            <h1>Welcome to NewUI!</h1>
            
            <!-- Reactive Counter -->
            <div data-ui-component="counter" data-ui-state='{"count": 0}'>
                <p>Count: <span data-ui-bind="count">0</span></p>
                {{ ui.button("Increment", onclick="increment") }}
                {{ ui.button("Reset", onclick="reset") }}
            </div>
            
            <!-- AJAX Form -->
            <form data-ui-submit="ajax:/api/save">
                {{ ui.input("name", placeholder="Enter your name") }}
                {{ ui.button("Save", type="submit") }}
            </form>
        </div>
        
        <script src="{{ url_for('newui.static', filename='newui.js') }}"></script>
        <script>
            NewUI.registerHandler('increment', function(element, event) {
                const componentId = NewUI.getComponentId(element);
                const state = NewUI.state[componentId];
                NewUI.setStateValue(componentId, 'count', (state.count || 0) + 1);
            });
            
            NewUI.registerHandler('reset', function(element, event) {
                const componentId = NewUI.getComponentId(element);
                NewUI.setStateValue(componentId, 'count', 0);
            });
        </script>
    </body>
    </html>
    ''', ui=ui)

if __name__ == '__main__':
    app.run(debug=True)
```

### 5-Minute Tutorial

**1. Create a Flask app with NewUI:**

```python
from flask import Flask
from newui import NewUI

app = Flask(__name__)
newui = NewUI(app)
```

**2. Use built-in components:**

```python
from newui import components as ui

# In your template
{{ ui.button("Click Me", onclick="handleClick") }}
{{ ui.input("email", type="email", placeholder="Enter email") }}
{{ ui.card("Card content", title="My Card") }}
```

**3. Add reactivity:**

```html
<!-- State-aware component -->
<div data-ui-component="todo-list" data-ui-state='{"items": []}'>
    <!-- Component content with data binding -->
    <span data-ui-bind="items.length">0</span> items
</div>
```

**4. Handle events:**

```javascript
NewUI.registerHandler('addTodo', function(element, event) {
    const componentId = NewUI.getComponentId(element);
    const state = NewUI.state[componentId];
    // Update state and UI automatically updates
    NewUI.setStateValue(componentId, 'items', [...state.items, newItem]);
});
```

## 🤖 AI-Assisted Development

**Developing with AI tools? Flask-NewUI includes the world's first AI Framework Schema (AFS) to make AI your expert coding partner.**

### What is AI Framework Schema?

The AI Framework Schema is a revolutionary machine-readable documentation format that makes AI models instantly expert in Flask-NewUI. Instead of generic suggestions, AI tools provide:

✅ **Framework-specific code generation**  
✅ **Contextual recommendations** (when to use Flask-NewUI vs alternatives)  
✅ **Idiomatic patterns** and best practices  
✅ **Targeted debugging assistance**  

### Using AFS with AI Tools

**1. Include the schema in your AI conversations:**
```
Please reference the Flask-NewUI AI Framework Schema when helping me:
[Paste contents of flask-newui.afs.json]
```

**2. Or reference it from the repository:**
```
Use the AI Framework Schema at: /flask-newui.afs.json
to understand Flask-NewUI capabilities and provide expert assistance.
```

**3. Example AI-powered development:**
```
Human: "Create a todo app with real-time updates"
AI: [With AFS] "Perfect! Flask-NewUI is ideal for this. Use WebSocket 
integration with component state management..."
```

### AFS Files in This Repository

- **`flask-newui.afs.json`** - Complete schema making AI an instant expert
- **`afs-spec.md`** - Full specification for the AFS standard  
- **`validate_afs.py`** - Tool to validate schema files
- **`AFS-README.md`** - Comprehensive AFS documentation

**Try it yourself:** Ask your AI assistant about Flask-NewUI while providing the AFS file. Watch it become an instant expert! 🚀

## Component System

### Built-in Components

All components are available via the `ui` global in templates:

- **Button**: `ui.button(text, type, variant, onclick, disabled, class_)`
- **Form**: `ui.form(content, action, method, ajax, csrf_token)`
- **Input**: `ui.input(name, type, value, placeholder, label, bind)`
- **Select**: `ui.select(name, options, selected, label, bind)`
- **Card**: `ui.card(content, title, footer, class_)`
- **Alert**: `ui.alert(message, type, dismissible, class_)`

### Custom Components

```python
@ui.component('my_component')
def my_component(title, content):
    return render_template('components/my_component.html', 
                         title=title, content=content)
```

## Event Handling

### Declarative Events

```html
<!-- Click handler -->
<button data-ui-click="handleClick">Click me</button>

<!-- AJAX handler -->
<button data-ui-click="ajax:/api/save">Save</button>

<!-- Form submission -->
<form data-ui-submit="ajax:/api/submit">
```

### JavaScript Integration

```javascript
// Register custom handler
NewUI.registerHandler('handleClick', function(element, event) {
    console.log('Button clicked!');
});

// Update component via AJAX
NewUI.updateComponent('component_id', data);
```

## State Management

### Server-Side State

```python
# In your route
ui.state.set_state('component_id', {'count': 0})
state = ui.state.get_state('component_id')
```

### Client-Side Binding

```html
<!-- Two-way data binding -->
<input data-ui-bind="user.name" value="{{ user.name }}">

<!-- State persistence -->
<div data-ui-component="counter" data-ui-state='{"count": 0}'>
```

## AJAX Partial Rendering

### Reactive Routes

```python
@app.route('/dashboard')
@ui.reactive
def dashboard():
    # Automatically handles partial updates
    return render_template('dashboard.html', data=get_data())
```

### Manual Partial Updates

```python
@app.route('/update/<component>')
def update_component(component):
    return ui.ajax.component_response(component, data=new_data)
```

## CSS Framework Integration

NewUI works seamlessly with any CSS framework:

### Tailwind CSS v4.0
```html
{{ ui.button("Save", class_="px-4 py-2 bg-blue-500 text-white rounded-lg hover:bg-blue-600") }}
{{ ui.input("email", class_="rounded-lg border-gray-300 shadow-sm focus:ring-blue-500") }}
```

**See the complete example:** `examples/tailwind_modern_ui.py` - A modern dashboard with dark mode, animations, and responsive design.

### Bootstrap
```html
{{ ui.button("Save", class="btn btn-primary") }}
{{ ui.input("email", class="form-control") }}
```

## 📚 Examples

Comprehensive examples are included in the `examples/` directory:

### Basic Examples
- **`todo_app.py`** - Complete todo application with AJAX forms
- **`form_binding.py`** - Two-way data binding demonstration
- **`basic_forms.py`** - Simple form handling and validation
- **`dynamic_content.py`** - Dynamic conditional content rendering
- **`dynamic_lists.py`** - Efficient list updates and rendering
- **`ajax_loading.py`** - Loading states and progress indicators
- **`component_lifecycle.py`** - Component lifecycle hooks demo
- **`tailwind_modern_ui.py`** - Modern dashboard with Tailwind CSS v4.0 and dark mode

### Advanced Examples  
- **`realtime_chat.py`** - Real-time chat with WebSocket integration
- **`state_management.py`** - Redux-like state management patterns
- **`nested_components.py`** - Component composition and nesting
- **`spa_routing.py`** - Single-page application routing
- **`debug_tools.py`** - Development tools and debugging helpers

### Quick Examples

**Todo List with Real-time Updates:**
```python
from flask import Flask
from newui import NewUI
from newui import components as ui

app = Flask(__name__)
newui = NewUI(app)

todos = []

@app.route('/')
def index():
    return render_template_string('''
    <div data-ui-component="todo-app" data-ui-state='{"todos": {{ todos | tojson }}}'>
        <form data-ui-submit="addTodo">
            {{ ui.input("todo", placeholder="Add new todo...") }}
            {{ ui.button("Add", type="submit") }}
        </form>
        <div data-ui-list="todos" data-ui-list-item="todo">
            <div class="todo-item">
                <span data-ui-bind="todo.text"></span>
                {{ ui.button("Delete", onclick="deleteTodo", data_todo_id="todo.id") }}
            </div>
        </div>
    </div>
    ''', ui=ui, todos=todos)
```

**Real-time Chat:**
```python
# With WebSocket support
from newui.websocket import NewUIWebSocket

socketio = SocketIO(app)
ws = NewUIWebSocket(app, socketio)

@socketio.on('send_message')
def handle_message(data):
    # Broadcast to all connected clients
    ws.broadcast_message({'type': 'new_message', 'message': data})
```

## 🔧 API Reference

### Core Classes

#### `NewUI(app=None)`
Main framework class for Flask integration.

```python
from newui import NewUI

newui = NewUI(app)  # or newui.init_app(app)
```

**Methods:**
- `init_app(app)` - Initialize with Flask app
- `reactive(func)` - Decorator for reactive routes
- `component(name)` - Decorator for custom components

#### `components` Module
Built-in UI components.

```python
from newui import components as ui

# Basic components
ui.button(text, onclick=None, type="button", variant="primary", disabled=False, class_="")
ui.input(name, type="text", value="", placeholder="", label=None, bind=None, required=False)
ui.form(action="", method="POST", ajax=False, csrf_token=None, class_="")
ui.select(name, options=[], selected=None, label=None, bind=None, class_="")

# Layout components  
ui.card(content, title=None, footer=None, class_="")
ui.alert(message, type="info", dismissible=False, class_="")
ui.modal(content, title=None, id=None, size="md", class_="")

# Advanced components
ui.list_render(items, item_template, bind=None, class_="")
ui.conditional(condition, content, else_content=None)
ui.loading_state(content, loading_text="Loading...", class_="")
```

### State Management

#### Client-Side State
```javascript
// Get component state
const state = NewUI.getState(componentId);

// Set single value
NewUI.setStateValue(componentId, 'key', value);

// Update multiple values
NewUI.updateState(componentId, {key1: value1, key2: value2});

// Subscribe to state changes
NewUI.onStateChange(componentId, callback);
```

#### Server-Side State
```python
from newui.stores import Store

# Create store
store = Store('myStore', initial_state={'count': 0})

# Dispatch actions
store.dispatch('increment', payload={'amount': 1})

# Subscribe to changes
store.subscribe(lambda state: print(f"New state: {state}"))
```

### WebSocket Integration

```python
from newui.websocket import NewUIWebSocket

ws = NewUIWebSocket(app, socketio)

# Update component state in real-time
ws.update_component_state('component-id', {'count': 42})

# Broadcast to all clients
ws.broadcast_message({'type': 'notification', 'message': 'Hello!'})

# Send to specific room
ws.broadcast_message({'type': 'update'}, room='chat-room')
```

### Development Tools

```python
from newui.devtools import init_debugger

# Enable debugging
debugger = init_debugger(app, enabled=True)

# In templates
{{ debug_code | safe }}  # Inject debug client code
```

## 🛠️ Development

### Project Structure
```
flask-newui/
├── newui/                 # Core framework
│   ├── __init__.py       # Main NewUI class
│   ├── components.py     # Built-in components
│   ├── composition.py    # Component composition
│   ├── devtools.py       # Development tools
│   ├── routing.py        # Route-based code splitting
│   ├── stores.py         # State management
│   ├── websocket.py      # WebSocket support
│   ├── cli.py           # Command line interface
│   ├── core/            # Core modules
│   │   ├── ajax.py      # AJAX handling
│   │   ├── components.py # Component system
│   │   ├── renderer.py   # Template rendering
│   │   └── state.py     # State management
│   └── static/          # Static assets
│       ├── newui.js     # Core JavaScript
│       └── newui.css    # Default styles
├── examples/             # Example applications
├── docs/                # Documentation
├── tests/               # Test suite
└── setup.py            # Package configuration
```

### Running Examples

```bash
# Install with examples
pip install flask-newui[examples]

# Run todo application
python examples/todo_app.py

# Run modern Tailwind CSS dashboard
python examples/tailwind_modern_ui.py

# Run real-time chat example
python examples/realtime_chat.py

# Run development tools demo
python examples/debug_tools.py
```

### Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes and add tests
4. Run tests: `python -m pytest tests/ -v`
5. Submit a pull request

## 📖 Documentation

- **[Getting Started Guide](docs/getting-started.md)** - Detailed setup and usage
- **[Component Reference](docs/components.md)** - Complete component documentation  
- **[State Management](docs/state-management.md)** - Advanced state patterns
- **[WebSocket Guide](docs/websockets.md)** - Real-time features
- **[Migration Guide](docs/migration.md)** - Moving from vanilla Flask
- **[Best Practices](docs/best-practices.md)** - Recommended patterns

## 🤝 Community

- **GitHub**: [flask-newui/flask-newui](https://github.com/smbrandonjr/flask-newui)
- **Issues**: [Report bugs or request features](https://github.com/smbrandonjr/flask-newui/issues)
- **Discussions**: [Community discussions](https://github.com/smbrandonjr/flask-newui/discussions)

## 💝 Support the Project

If Flask-NewUI has helped you build amazing applications, consider supporting its continued development:

**Bitcoin**: `3DEMZi7sx1ZJWwGi8jzq3yqevGoyczFn9X`

Your contributions help maintain and improve this open-source project. Thank you for your support! 🙏

## 📄 License

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

## ⭐ Why NewUI?

**For Flask Developers:**
- Familiar Jinja2 syntax with reactive enhancements
- No need to learn a completely new framework
- Gradual adoption - use as much or as little as needed
- Maintains Flask's simplicity and patterns

**For Modern Development:**
- Component-based architecture
- Real-time updates with WebSockets
- State management for complex UIs
- Development tools for debugging
- AI Framework Schema for expert AI assistance

**For Production:**
- Progressive enhancement ensures accessibility
- Server-side rendering for SEO
- Works without JavaScript for core functionality
- Easy deployment with existing Flask infrastructure

---

**Get started today and transform your Flask applications with modern UI capabilities!**

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "flask-newui",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": "NewUI Contributors <contact@flask-newui.dev>",
    "keywords": "flask, jinja2, frontend, framework, reactive, ui, components",
    "author": null,
    "author_email": "NewUI Contributors <contact@flask-newui.dev>",
    "download_url": "https://files.pythonhosted.org/packages/35/3f/d4f833ae7ae5f3dc54efc69b098c18e5cca4c46e5e442d2ad111af592984/flask_newui-1.0.0.tar.gz",
    "platform": null,
    "description": "# NewUI Framework\r\n\r\n[![PyPI version](https://badge.fury.io/py/flask-newui.svg)](https://badge.fury.io/py/flask-newui)\r\n[![Python Support](https://img.shields.io/pypi/pyversions/flask-newui.svg)](https://pypi.org/project/flask-newui/)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n[![AI Framework Schema](https://img.shields.io/badge/AI%20Framework%20Schema-Available-brightgreen.svg)](#\ud83e\udd16-ai-assisted-development)\r\n\r\n**A modern reactive frontend framework that bridges Flask/Jinja2 with modern UI capabilities**\r\n\r\nNewUI transforms traditional Flask/Jinja2 development by adding reactive capabilities while maintaining the simplicity and server-side rendering benefits that make Flask development straightforward. Build sleek, intuitive frontends that rival modern frameworks without leaving the Flask ecosystem.\r\n\r\n> **\ud83e\udd16 NEW: AI-Powered Development**  \r\n> Flask-NewUI includes the world's first **AI Framework Schema (AFS)** - making AI tools instant experts in Flask-NewUI development. Get framework-specific code generation, smart recommendations, and expert debugging assistance. [Learn more \u2193](#\ud83e\udd16-ai-assisted-development)\r\n\r\n## \u2728 Features\r\n\r\n**\ud83c\udfaf Core Capabilities**\r\n- **Zero Build Step**: Works without webpack or compilation\r\n- **Progressive Enhancement**: Full functionality without JavaScript, enhanced with it\r\n- **Flask-Native**: Seamless integration with Flask's request/response cycle\r\n- **CSS Framework Agnostic**: Works with Tailwind, Bootstrap, or custom CSS\r\n- **Jinja2-First**: All components leverage Jinja2's existing capabilities\r\n\r\n**\ud83e\udd16 AI-Optimized Development**\r\n- **AI Framework Schema (AFS)**: Comprehensive machine-readable documentation\r\n- **Instant AI Expertise**: AI tools become Flask-NewUI experts immediately\r\n- **Better Code Generation**: AI generates idiomatic Flask-NewUI code\r\n- **Smart Recommendations**: AI knows when to use Flask-NewUI vs other solutions\r\n\r\n**\ud83d\ude80 Phase 1: Foundation**\r\n- \u2705 Component macro system with parameter validation\r\n- \u2705 Automatic AJAX partial rendering\r\n- \u2705 Basic event handling (click, submit, change)\r\n- \u2705 State persistence via data attributes\r\n- \u2705 Flask extension for easy integration\r\n\r\n**\u26a1 Phase 2: Enhanced Interactivity**\r\n- \u2705 Two-way data binding for forms\r\n- \u2705 Conditional rendering helpers\r\n- \u2705 List rendering with efficient updates\r\n- \u2705 Component lifecycle hooks\r\n- \u2705 Built-in loading states\r\n\r\n**\ud83d\udd25 Phase 3: Advanced Features**\r\n- \u2705 WebSocket support for real-time updates\r\n- \u2705 Component composition patterns\r\n- \u2705 State stores for complex apps\r\n- \u2705 Route-based code splitting\r\n- \u2705 Development tools (debugger, component inspector)\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\npip install flask-newui\r\n\r\n# For WebSocket support\r\npip install flask-newui[websocket]\r\n\r\n# For development\r\npip install flask-newui[dev]\r\n```\r\n\r\n### Basic Usage\r\n\r\n```python\r\nfrom flask import Flask, render_template_string\r\nfrom newui import NewUI\r\nfrom newui import components as ui\r\n\r\napp = Flask(__name__)\r\nnewui = NewUI(app)\r\n\r\n# Simple reactive page\r\n@app.route('/')\r\ndef index():\r\n    return render_template_string('''\r\n    <!DOCTYPE html>\r\n    <html>\r\n    <head>\r\n        <title>NewUI Demo</title>\r\n        <link href=\"{{ url_for('newui.static', filename='newui.css') }}\" rel=\"stylesheet\">\r\n    </head>\r\n    <body>\r\n        <div class=\"container\">\r\n            <h1>Welcome to NewUI!</h1>\r\n            \r\n            <!-- Reactive Counter -->\r\n            <div data-ui-component=\"counter\" data-ui-state='{\"count\": 0}'>\r\n                <p>Count: <span data-ui-bind=\"count\">0</span></p>\r\n                {{ ui.button(\"Increment\", onclick=\"increment\") }}\r\n                {{ ui.button(\"Reset\", onclick=\"reset\") }}\r\n            </div>\r\n            \r\n            <!-- AJAX Form -->\r\n            <form data-ui-submit=\"ajax:/api/save\">\r\n                {{ ui.input(\"name\", placeholder=\"Enter your name\") }}\r\n                {{ ui.button(\"Save\", type=\"submit\") }}\r\n            </form>\r\n        </div>\r\n        \r\n        <script src=\"{{ url_for('newui.static', filename='newui.js') }}\"></script>\r\n        <script>\r\n            NewUI.registerHandler('increment', function(element, event) {\r\n                const componentId = NewUI.getComponentId(element);\r\n                const state = NewUI.state[componentId];\r\n                NewUI.setStateValue(componentId, 'count', (state.count || 0) + 1);\r\n            });\r\n            \r\n            NewUI.registerHandler('reset', function(element, event) {\r\n                const componentId = NewUI.getComponentId(element);\r\n                NewUI.setStateValue(componentId, 'count', 0);\r\n            });\r\n        </script>\r\n    </body>\r\n    </html>\r\n    ''', ui=ui)\r\n\r\nif __name__ == '__main__':\r\n    app.run(debug=True)\r\n```\r\n\r\n### 5-Minute Tutorial\r\n\r\n**1. Create a Flask app with NewUI:**\r\n\r\n```python\r\nfrom flask import Flask\r\nfrom newui import NewUI\r\n\r\napp = Flask(__name__)\r\nnewui = NewUI(app)\r\n```\r\n\r\n**2. Use built-in components:**\r\n\r\n```python\r\nfrom newui import components as ui\r\n\r\n# In your template\r\n{{ ui.button(\"Click Me\", onclick=\"handleClick\") }}\r\n{{ ui.input(\"email\", type=\"email\", placeholder=\"Enter email\") }}\r\n{{ ui.card(\"Card content\", title=\"My Card\") }}\r\n```\r\n\r\n**3. Add reactivity:**\r\n\r\n```html\r\n<!-- State-aware component -->\r\n<div data-ui-component=\"todo-list\" data-ui-state='{\"items\": []}'>\r\n    <!-- Component content with data binding -->\r\n    <span data-ui-bind=\"items.length\">0</span> items\r\n</div>\r\n```\r\n\r\n**4. Handle events:**\r\n\r\n```javascript\r\nNewUI.registerHandler('addTodo', function(element, event) {\r\n    const componentId = NewUI.getComponentId(element);\r\n    const state = NewUI.state[componentId];\r\n    // Update state and UI automatically updates\r\n    NewUI.setStateValue(componentId, 'items', [...state.items, newItem]);\r\n});\r\n```\r\n\r\n## \ud83e\udd16 AI-Assisted Development\r\n\r\n**Developing with AI tools? Flask-NewUI includes the world's first AI Framework Schema (AFS) to make AI your expert coding partner.**\r\n\r\n### What is AI Framework Schema?\r\n\r\nThe AI Framework Schema is a revolutionary machine-readable documentation format that makes AI models instantly expert in Flask-NewUI. Instead of generic suggestions, AI tools provide:\r\n\r\n\u2705 **Framework-specific code generation**  \r\n\u2705 **Contextual recommendations** (when to use Flask-NewUI vs alternatives)  \r\n\u2705 **Idiomatic patterns** and best practices  \r\n\u2705 **Targeted debugging assistance**  \r\n\r\n### Using AFS with AI Tools\r\n\r\n**1. Include the schema in your AI conversations:**\r\n```\r\nPlease reference the Flask-NewUI AI Framework Schema when helping me:\r\n[Paste contents of flask-newui.afs.json]\r\n```\r\n\r\n**2. Or reference it from the repository:**\r\n```\r\nUse the AI Framework Schema at: /flask-newui.afs.json\r\nto understand Flask-NewUI capabilities and provide expert assistance.\r\n```\r\n\r\n**3. Example AI-powered development:**\r\n```\r\nHuman: \"Create a todo app with real-time updates\"\r\nAI: [With AFS] \"Perfect! Flask-NewUI is ideal for this. Use WebSocket \r\nintegration with component state management...\"\r\n```\r\n\r\n### AFS Files in This Repository\r\n\r\n- **`flask-newui.afs.json`** - Complete schema making AI an instant expert\r\n- **`afs-spec.md`** - Full specification for the AFS standard  \r\n- **`validate_afs.py`** - Tool to validate schema files\r\n- **`AFS-README.md`** - Comprehensive AFS documentation\r\n\r\n**Try it yourself:** Ask your AI assistant about Flask-NewUI while providing the AFS file. Watch it become an instant expert! \ud83d\ude80\r\n\r\n## Component System\r\n\r\n### Built-in Components\r\n\r\nAll components are available via the `ui` global in templates:\r\n\r\n- **Button**: `ui.button(text, type, variant, onclick, disabled, class_)`\r\n- **Form**: `ui.form(content, action, method, ajax, csrf_token)`\r\n- **Input**: `ui.input(name, type, value, placeholder, label, bind)`\r\n- **Select**: `ui.select(name, options, selected, label, bind)`\r\n- **Card**: `ui.card(content, title, footer, class_)`\r\n- **Alert**: `ui.alert(message, type, dismissible, class_)`\r\n\r\n### Custom Components\r\n\r\n```python\r\n@ui.component('my_component')\r\ndef my_component(title, content):\r\n    return render_template('components/my_component.html', \r\n                         title=title, content=content)\r\n```\r\n\r\n## Event Handling\r\n\r\n### Declarative Events\r\n\r\n```html\r\n<!-- Click handler -->\r\n<button data-ui-click=\"handleClick\">Click me</button>\r\n\r\n<!-- AJAX handler -->\r\n<button data-ui-click=\"ajax:/api/save\">Save</button>\r\n\r\n<!-- Form submission -->\r\n<form data-ui-submit=\"ajax:/api/submit\">\r\n```\r\n\r\n### JavaScript Integration\r\n\r\n```javascript\r\n// Register custom handler\r\nNewUI.registerHandler('handleClick', function(element, event) {\r\n    console.log('Button clicked!');\r\n});\r\n\r\n// Update component via AJAX\r\nNewUI.updateComponent('component_id', data);\r\n```\r\n\r\n## State Management\r\n\r\n### Server-Side State\r\n\r\n```python\r\n# In your route\r\nui.state.set_state('component_id', {'count': 0})\r\nstate = ui.state.get_state('component_id')\r\n```\r\n\r\n### Client-Side Binding\r\n\r\n```html\r\n<!-- Two-way data binding -->\r\n<input data-ui-bind=\"user.name\" value=\"{{ user.name }}\">\r\n\r\n<!-- State persistence -->\r\n<div data-ui-component=\"counter\" data-ui-state='{\"count\": 0}'>\r\n```\r\n\r\n## AJAX Partial Rendering\r\n\r\n### Reactive Routes\r\n\r\n```python\r\n@app.route('/dashboard')\r\n@ui.reactive\r\ndef dashboard():\r\n    # Automatically handles partial updates\r\n    return render_template('dashboard.html', data=get_data())\r\n```\r\n\r\n### Manual Partial Updates\r\n\r\n```python\r\n@app.route('/update/<component>')\r\ndef update_component(component):\r\n    return ui.ajax.component_response(component, data=new_data)\r\n```\r\n\r\n## CSS Framework Integration\r\n\r\nNewUI works seamlessly with any CSS framework:\r\n\r\n### Tailwind CSS v4.0\r\n```html\r\n{{ ui.button(\"Save\", class_=\"px-4 py-2 bg-blue-500 text-white rounded-lg hover:bg-blue-600\") }}\r\n{{ ui.input(\"email\", class_=\"rounded-lg border-gray-300 shadow-sm focus:ring-blue-500\") }}\r\n```\r\n\r\n**See the complete example:** `examples/tailwind_modern_ui.py` - A modern dashboard with dark mode, animations, and responsive design.\r\n\r\n### Bootstrap\r\n```html\r\n{{ ui.button(\"Save\", class=\"btn btn-primary\") }}\r\n{{ ui.input(\"email\", class=\"form-control\") }}\r\n```\r\n\r\n## \ud83d\udcda Examples\r\n\r\nComprehensive examples are included in the `examples/` directory:\r\n\r\n### Basic Examples\r\n- **`todo_app.py`** - Complete todo application with AJAX forms\r\n- **`form_binding.py`** - Two-way data binding demonstration\r\n- **`basic_forms.py`** - Simple form handling and validation\r\n- **`dynamic_content.py`** - Dynamic conditional content rendering\r\n- **`dynamic_lists.py`** - Efficient list updates and rendering\r\n- **`ajax_loading.py`** - Loading states and progress indicators\r\n- **`component_lifecycle.py`** - Component lifecycle hooks demo\r\n- **`tailwind_modern_ui.py`** - Modern dashboard with Tailwind CSS v4.0 and dark mode\r\n\r\n### Advanced Examples  \r\n- **`realtime_chat.py`** - Real-time chat with WebSocket integration\r\n- **`state_management.py`** - Redux-like state management patterns\r\n- **`nested_components.py`** - Component composition and nesting\r\n- **`spa_routing.py`** - Single-page application routing\r\n- **`debug_tools.py`** - Development tools and debugging helpers\r\n\r\n### Quick Examples\r\n\r\n**Todo List with Real-time Updates:**\r\n```python\r\nfrom flask import Flask\r\nfrom newui import NewUI\r\nfrom newui import components as ui\r\n\r\napp = Flask(__name__)\r\nnewui = NewUI(app)\r\n\r\ntodos = []\r\n\r\n@app.route('/')\r\ndef index():\r\n    return render_template_string('''\r\n    <div data-ui-component=\"todo-app\" data-ui-state='{\"todos\": {{ todos | tojson }}}'>\r\n        <form data-ui-submit=\"addTodo\">\r\n            {{ ui.input(\"todo\", placeholder=\"Add new todo...\") }}\r\n            {{ ui.button(\"Add\", type=\"submit\") }}\r\n        </form>\r\n        <div data-ui-list=\"todos\" data-ui-list-item=\"todo\">\r\n            <div class=\"todo-item\">\r\n                <span data-ui-bind=\"todo.text\"></span>\r\n                {{ ui.button(\"Delete\", onclick=\"deleteTodo\", data_todo_id=\"todo.id\") }}\r\n            </div>\r\n        </div>\r\n    </div>\r\n    ''', ui=ui, todos=todos)\r\n```\r\n\r\n**Real-time Chat:**\r\n```python\r\n# With WebSocket support\r\nfrom newui.websocket import NewUIWebSocket\r\n\r\nsocketio = SocketIO(app)\r\nws = NewUIWebSocket(app, socketio)\r\n\r\n@socketio.on('send_message')\r\ndef handle_message(data):\r\n    # Broadcast to all connected clients\r\n    ws.broadcast_message({'type': 'new_message', 'message': data})\r\n```\r\n\r\n## \ud83d\udd27 API Reference\r\n\r\n### Core Classes\r\n\r\n#### `NewUI(app=None)`\r\nMain framework class for Flask integration.\r\n\r\n```python\r\nfrom newui import NewUI\r\n\r\nnewui = NewUI(app)  # or newui.init_app(app)\r\n```\r\n\r\n**Methods:**\r\n- `init_app(app)` - Initialize with Flask app\r\n- `reactive(func)` - Decorator for reactive routes\r\n- `component(name)` - Decorator for custom components\r\n\r\n#### `components` Module\r\nBuilt-in UI components.\r\n\r\n```python\r\nfrom newui import components as ui\r\n\r\n# Basic components\r\nui.button(text, onclick=None, type=\"button\", variant=\"primary\", disabled=False, class_=\"\")\r\nui.input(name, type=\"text\", value=\"\", placeholder=\"\", label=None, bind=None, required=False)\r\nui.form(action=\"\", method=\"POST\", ajax=False, csrf_token=None, class_=\"\")\r\nui.select(name, options=[], selected=None, label=None, bind=None, class_=\"\")\r\n\r\n# Layout components  \r\nui.card(content, title=None, footer=None, class_=\"\")\r\nui.alert(message, type=\"info\", dismissible=False, class_=\"\")\r\nui.modal(content, title=None, id=None, size=\"md\", class_=\"\")\r\n\r\n# Advanced components\r\nui.list_render(items, item_template, bind=None, class_=\"\")\r\nui.conditional(condition, content, else_content=None)\r\nui.loading_state(content, loading_text=\"Loading...\", class_=\"\")\r\n```\r\n\r\n### State Management\r\n\r\n#### Client-Side State\r\n```javascript\r\n// Get component state\r\nconst state = NewUI.getState(componentId);\r\n\r\n// Set single value\r\nNewUI.setStateValue(componentId, 'key', value);\r\n\r\n// Update multiple values\r\nNewUI.updateState(componentId, {key1: value1, key2: value2});\r\n\r\n// Subscribe to state changes\r\nNewUI.onStateChange(componentId, callback);\r\n```\r\n\r\n#### Server-Side State\r\n```python\r\nfrom newui.stores import Store\r\n\r\n# Create store\r\nstore = Store('myStore', initial_state={'count': 0})\r\n\r\n# Dispatch actions\r\nstore.dispatch('increment', payload={'amount': 1})\r\n\r\n# Subscribe to changes\r\nstore.subscribe(lambda state: print(f\"New state: {state}\"))\r\n```\r\n\r\n### WebSocket Integration\r\n\r\n```python\r\nfrom newui.websocket import NewUIWebSocket\r\n\r\nws = NewUIWebSocket(app, socketio)\r\n\r\n# Update component state in real-time\r\nws.update_component_state('component-id', {'count': 42})\r\n\r\n# Broadcast to all clients\r\nws.broadcast_message({'type': 'notification', 'message': 'Hello!'})\r\n\r\n# Send to specific room\r\nws.broadcast_message({'type': 'update'}, room='chat-room')\r\n```\r\n\r\n### Development Tools\r\n\r\n```python\r\nfrom newui.devtools import init_debugger\r\n\r\n# Enable debugging\r\ndebugger = init_debugger(app, enabled=True)\r\n\r\n# In templates\r\n{{ debug_code | safe }}  # Inject debug client code\r\n```\r\n\r\n## \ud83d\udee0\ufe0f Development\r\n\r\n### Project Structure\r\n```\r\nflask-newui/\r\n\u251c\u2500\u2500 newui/                 # Core framework\r\n\u2502   \u251c\u2500\u2500 __init__.py       # Main NewUI class\r\n\u2502   \u251c\u2500\u2500 components.py     # Built-in components\r\n\u2502   \u251c\u2500\u2500 composition.py    # Component composition\r\n\u2502   \u251c\u2500\u2500 devtools.py       # Development tools\r\n\u2502   \u251c\u2500\u2500 routing.py        # Route-based code splitting\r\n\u2502   \u251c\u2500\u2500 stores.py         # State management\r\n\u2502   \u251c\u2500\u2500 websocket.py      # WebSocket support\r\n\u2502   \u251c\u2500\u2500 cli.py           # Command line interface\r\n\u2502   \u251c\u2500\u2500 core/            # Core modules\r\n\u2502   \u2502   \u251c\u2500\u2500 ajax.py      # AJAX handling\r\n\u2502   \u2502   \u251c\u2500\u2500 components.py # Component system\r\n\u2502   \u2502   \u251c\u2500\u2500 renderer.py   # Template rendering\r\n\u2502   \u2502   \u2514\u2500\u2500 state.py     # State management\r\n\u2502   \u2514\u2500\u2500 static/          # Static assets\r\n\u2502       \u251c\u2500\u2500 newui.js     # Core JavaScript\r\n\u2502       \u2514\u2500\u2500 newui.css    # Default styles\r\n\u251c\u2500\u2500 examples/             # Example applications\r\n\u251c\u2500\u2500 docs/                # Documentation\r\n\u251c\u2500\u2500 tests/               # Test suite\r\n\u2514\u2500\u2500 setup.py            # Package configuration\r\n```\r\n\r\n### Running Examples\r\n\r\n```bash\r\n# Install with examples\r\npip install flask-newui[examples]\r\n\r\n# Run todo application\r\npython examples/todo_app.py\r\n\r\n# Run modern Tailwind CSS dashboard\r\npython examples/tailwind_modern_ui.py\r\n\r\n# Run real-time chat example\r\npython examples/realtime_chat.py\r\n\r\n# Run development tools demo\r\npython examples/debug_tools.py\r\n```\r\n\r\n### Contributing\r\n\r\n1. Fork the repository\r\n2. Create a feature branch: `git checkout -b feature-name`\r\n3. Make your changes and add tests\r\n4. Run tests: `python -m pytest tests/ -v`\r\n5. Submit a pull request\r\n\r\n## \ud83d\udcd6 Documentation\r\n\r\n- **[Getting Started Guide](docs/getting-started.md)** - Detailed setup and usage\r\n- **[Component Reference](docs/components.md)** - Complete component documentation  \r\n- **[State Management](docs/state-management.md)** - Advanced state patterns\r\n- **[WebSocket Guide](docs/websockets.md)** - Real-time features\r\n- **[Migration Guide](docs/migration.md)** - Moving from vanilla Flask\r\n- **[Best Practices](docs/best-practices.md)** - Recommended patterns\r\n\r\n## \ud83e\udd1d Community\r\n\r\n- **GitHub**: [flask-newui/flask-newui](https://github.com/smbrandonjr/flask-newui)\r\n- **Issues**: [Report bugs or request features](https://github.com/smbrandonjr/flask-newui/issues)\r\n- **Discussions**: [Community discussions](https://github.com/smbrandonjr/flask-newui/discussions)\r\n\r\n## \ud83d\udc9d Support the Project\r\n\r\nIf Flask-NewUI has helped you build amazing applications, consider supporting its continued development:\r\n\r\n**Bitcoin**: `3DEMZi7sx1ZJWwGi8jzq3yqevGoyczFn9X`\r\n\r\nYour contributions help maintain and improve this open-source project. Thank you for your support! \ud83d\ude4f\r\n\r\n## \ud83d\udcc4 License\r\n\r\nMIT License - see [LICENSE](LICENSE) file for details.\r\n\r\n## \u2b50 Why NewUI?\r\n\r\n**For Flask Developers:**\r\n- Familiar Jinja2 syntax with reactive enhancements\r\n- No need to learn a completely new framework\r\n- Gradual adoption - use as much or as little as needed\r\n- Maintains Flask's simplicity and patterns\r\n\r\n**For Modern Development:**\r\n- Component-based architecture\r\n- Real-time updates with WebSockets\r\n- State management for complex UIs\r\n- Development tools for debugging\r\n- AI Framework Schema for expert AI assistance\r\n\r\n**For Production:**\r\n- Progressive enhancement ensures accessibility\r\n- Server-side rendering for SEO\r\n- Works without JavaScript for core functionality\r\n- Easy deployment with existing Flask infrastructure\r\n\r\n---\r\n\r\n**Get started today and transform your Flask applications with modern UI capabilities!**\r\n",
    "bugtrack_url": null,
    "license": "MIT License\r\n        \r\n        Copyright (c) 2025 Flask-NewUI Framework Contributors\r\n        \r\n        Permission is hereby granted, free of charge, to any person obtaining a copy\r\n        of this software and associated documentation files (the \"Software\"), to deal\r\n        in the Software without restriction, including without limitation the rights\r\n        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\r\n        copies of the Software, and to permit persons to whom the Software is\r\n        furnished to do so, subject to the following conditions:\r\n        \r\n        The above copyright notice and this permission notice shall be included in all\r\n        copies or substantial portions of the Software.\r\n        \r\n        THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\r\n        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\r\n        SOFTWARE.",
    "summary": "A modern reactive frontend framework that bridges Flask/Jinja2 with modern UI capabilities",
    "version": "1.0.0",
    "project_urls": {
        "Bug Reports": "https://github.com/smbrandonjr/flask-newui/issues",
        "Changelog": "https://github.com/smbrandonjr/flask-newui/blob/main/CHANGELOG.md",
        "Documentation": "https://flask-newui.dev/docs",
        "Homepage": "https://github.com/smbrandonjr/flask-newui",
        "Repository": "https://github.com/smbrandonjr/flask-newui"
    },
    "split_keywords": [
        "flask",
        " jinja2",
        " frontend",
        " framework",
        " reactive",
        " ui",
        " components"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "9aee914a971724105431cc15a6a51b78879e28ab5ac3104efa708c648a992b37",
                "md5": "7c225e965906afca1a0b5503cbfd2537",
                "sha256": "becbd43d456f6a96e00bdd73cfbf37536508e8e747d39f89ebe4a09566a90cd2"
            },
            "downloads": -1,
            "filename": "flask_newui-1.0.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "7c225e965906afca1a0b5503cbfd2537",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 56907,
            "upload_time": "2025-07-24T14:32:16",
            "upload_time_iso_8601": "2025-07-24T14:32:16.775077Z",
            "url": "https://files.pythonhosted.org/packages/9a/ee/914a971724105431cc15a6a51b78879e28ab5ac3104efa708c648a992b37/flask_newui-1.0.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "353fd4f833ae7ae5f3dc54efc69b098c18e5cca4c46e5e442d2ad111af592984",
                "md5": "905159b9b6290914c3f3dd6e30d70e97",
                "sha256": "8bd32bcdda83cb88db7ff2c829dc6f1c9d2252af4679ba7a3436eb8c1249c23e"
            },
            "downloads": -1,
            "filename": "flask_newui-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "905159b9b6290914c3f3dd6e30d70e97",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 115623,
            "upload_time": "2025-07-24T14:32:18",
            "upload_time_iso_8601": "2025-07-24T14:32:18.288620Z",
            "url": "https://files.pythonhosted.org/packages/35/3f/d4f833ae7ae5f3dc54efc69b098c18e5cca4c46e5e442d2ad111af592984/flask_newui-1.0.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-24 14:32:18",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "smbrandonjr",
    "github_project": "flask-newui",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "flask-newui"
}