chakra-qtquick 0.5.3
A modern QML component library inspired by Chakra UI
Requires Python: >=3.8
Keywords: qml, qt, pyside6, ui, components, chakra-ui

# Chakra UI QML

A modern, accessible, and customizable QML component library inspired by [Chakra UI](https://chakra-ui.com/).

## Features

- 🎨 **33+ Components** - Buttons, Inputs, Cards, Menus, Dialogs, Sidebar and more
- 🌓 **Dark Mode** - Built-in theme system with light/dark modes
- ⚡ **High Performance** - Optimized rendering with minimal overhead
- 🪟 **Frameless Window** - Native Windows DWM shadow and custom title bar
- 🎯 **Type Safe** - Full PySide6 integration with type hints
- 📱 **Responsive** - Adaptive layouts and sizing system
- ♿ **Accessible** - ARIA-compliant components (where applicable)

## Installation

```bash
pip install chakra-qtquick
```

## Quick Start

### Basic Usage

```python
import sys
from PySide6.QtGui import QGuiApplication
from PySide6.QtQml import QQmlApplicationEngine
from PySide6.QtQuickControls2 import QQuickStyle
from chakra_ui import init

QQuickStyle.setStyle("Basic")
app = QGuiApplication(sys.argv)
engine = QQmlApplicationEngine()
init(engine)  # 注册 Chakra 组件
engine.load("main.qml")
sys.exit(app.exec())
```

### QML Example

```qml
import QtQuick
import Chakra 1.0

CWindow {
    width: 800
    height: 600
    title: "My App"
    
    Column {
        spacing: 16
        anchors.centerIn: parent
        
        CButton {
            text: "Click Me"
            colorScheme: "blue"
            onClicked: console.log("Clicked!")
        }
        
        CInput {
            placeholderText: "Enter text..."
            variant: "outline"
        }
        
        CCard {
            title: "Welcome"
            description: "This is a Chakra UI component"
            width: 300
        }
    }
}
```

## Available Components

### Layout
- `CBox` - Flexible container with styling props
- `CFlex` - Flexbox layout container
- `CCenter` - Center alignment container
- `CContainer` - Responsive container with max-width

### Forms
- `CButton` - Versatile button with variants and sizes
- `CInput` - Text input with validation states
- `CCheckbox` - Checkbox with indeterminate state
- `CSwitch` - Toggle switch with labels
- `CSelect` - Dropdown select with search

### Data Display
- `CCard` - Content card with header/footer
- `CBadge` - Small status indicator
- `CTag` - Removable tag component
- `CProgress` - Progress bar with variants
- `CSpinner` - Loading spinner

### Feedback
- `CAlert` - Alert messages with status
- `CTooltip` - Hover tooltip

### Overlay
- `CDialog` - Modal dialog
- `CDrawer` - Side drawer/panel
- `CMenu` - Dropdown menu
- `CMenuItem` - Menu item component

### Navigation
- `CPagination` - Pagination controls
- `CSegmentedControl` - Segmented picker
- `CSidebar` - Collapsible sidebar navigation
- `CSidebarItem` - Sidebar navigation item
- `CSidebarGroup` - Sidebar item group
- `CSidebarSeparator` - Sidebar separator

### Other
- `CWindow` - Frameless window with native shadow
- `CIcon` - Icon component with 100+ icons
- `CScrollBar` - Custom scrollbar
- `CScrollArea` - Scrollable area
- `CActionBar` - Floating action bar

## Theme Customization

The library uses a centralized `AppStyle` singleton for theming:

```qml
// Toggle theme
AppStyle.toggleTheme()

// Check current theme
if (AppStyle.isDark) {
    // Dark mode
}

// Access theme colors
color: AppStyle.primaryColor
color: AppStyle.textColor
color: AppStyle.backgroundColor
```

## Component Props

### CButton

```qml
CButton {
    text: "Button"
    variant: "solid"        // solid, outline, ghost, link
    colorScheme: "blue"     // blue, green, red, purple, etc.
    size: "md"              // sm, md, lg
    leftIcon: "check"
    rightIcon: "arrow-right"
    isLoading: false
    fullWidth: false
}
```

### CInput

```qml
CInput {
    placeholderText: "Enter text"
    variant: "outline"      // outline, filled, flushed
    size: "md"              // sm, md, lg
    isInvalid: false
    isDisabled: false
    isClearable: true
    type: "text"            // text, password
}
```

### CCard

```qml
CCard {
    title: "Card Title"
    description: "Card description"
    variant: "elevated"     // elevated, outline, filled, subtle
    size: "md"              // sm, md, lg
    
    // Custom content
    CButton { text: "Action" }
}
```

## Frameless Window

Create modern frameless windows with native Windows shadow:

```qml
import Chakra 1.0

CWindow {
    width: 1280
    height: 800
    title: "My App"
    
    showTitleBar: true
    showThemeToggle: true
    showMinimize: true
    showMaximize: true
    showClose: true
    shadowEnabled: true     // Native DWM shadow on Windows
    
    // Your content here
}
```

## Performance

This library is optimized for performance:

- ✅ No unnecessary `layer.effect` usage
- ✅ Efficient property bindings
- ✅ Cached color mappings in `AppStyle`
- ✅ Native Windows API for frameless window
- ✅ Minimal animation overhead

## Examples

Check the `demo` folder for complete examples:

- Basic components showcase
- Form validation
- Data tables
- Dashboard layouts
- Settings pages

## Requirements

- Python >= 3.8
- PySide6 >= 6.5.0

## Testing

This library includes a comprehensive test suite for both QML components and Python modules.

### Running Tests

```bash
# Run QML component tests
python tests/run_qml_tests.py

# Run Python unit tests
python tests/run_python_tests.py
```

See [tests/README.md](tests/README.md) for detailed testing documentation.

## License

MIT License - see [LICENSE](LICENSE) file for details

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Credits

Inspired by [Chakra UI](https://chakra-ui.com/) by Segun Adebayo.

## Author

ASLant

## Documentation

- [Quick Reference](docs/QUICK_REFERENCE.md) - 组件快速参考指南
- [Component API](docs/Chakra.md) - 完整组件 API 文档
- [Build Guide](docs/BUILD.md) - 构建和发布指南

## Links

- [GitHub Repository](https://github.com/Y-ASLant/chakra-ui-qml)
- [Documentation](https://github.com/Y-ASLant/chakra-ui-qml/tree/main/docs)
- [Issue Tracker](https://github.com/Y-ASLant/chakra-ui-qml/issues)