86 lines
2.6 KiB
Markdown
86 lines
2.6 KiB
Markdown
# NiceGUI Extensions (niceguiex) - Project Overview
|
|
|
|
## Project Structure
|
|
|
|
This project is a collection of extensions for NiceGUI, organized as a modular package that can be extended with new components and utilities.
|
|
|
|
### Current Structure
|
|
```
|
|
src/
|
|
niceguiex/
|
|
__init__.py
|
|
async_elements/
|
|
__init__.py
|
|
base.py # AsyncElement base class
|
|
elements.py # Pre-built async element types
|
|
components/
|
|
__init__.py
|
|
file_drop.py # FileDrop and ImageDrop components
|
|
chat_input.py # ChatInput component
|
|
```
|
|
|
|
## Key Components
|
|
|
|
### 1. Async Elements (`niceguiex.async_elements`)
|
|
Provides async-aware UI elements that can perform async operations during initialization while maintaining full typing support.
|
|
|
|
**Base Class:** `AsyncElement[T]` - Generic base for creating async elements
|
|
**Pre-built Elements:**
|
|
- AsyncColumn, AsyncRow, AsyncCard
|
|
- AsyncDialog, AsyncTabs, AsyncScrollArea
|
|
- AsyncExpansion, AsyncCarousel, AsyncMenu
|
|
- And more...
|
|
|
|
### 2. Components (`niceguiex.components`)
|
|
|
|
#### ChatInput
|
|
A textarea component optimized for chat interfaces:
|
|
- Enter to send message
|
|
- Shift+Enter for new line
|
|
- Callback-based message handling
|
|
|
|
#### FileDrop
|
|
Drag-and-drop file upload component:
|
|
- Visual drag-over feedback
|
|
- Click to browse or drag & drop functionality
|
|
- Async callback support with file name, type, and content
|
|
- Support for single or multiple file uploads
|
|
- Customizable file type filtering
|
|
|
|
#### ImageDrop
|
|
Specialized FileDrop for images:
|
|
- Returns PIL Image objects
|
|
- Handles image-specific processing
|
|
- Support for single or multiple image uploads
|
|
|
|
## Import Convention
|
|
|
|
The package uses a submodule structure to organize different types of extensions:
|
|
|
|
```python
|
|
from niceguiex.async_elements import AsyncColumn, AsyncCard
|
|
from niceguiex.components import ChatInput, FileDrop, ImageDrop
|
|
```
|
|
|
|
## Technical Notes
|
|
|
|
- **Async Module Name:** Originally planned as `niceguiex.async` but changed to `async_elements` because `async` is a Python reserved keyword
|
|
- **Type Safety:** All components maintain full type hints for IDE support
|
|
- **Inheritance Pattern:** Components can be used via generic `AsyncElement[T]` or by inheriting from specific types
|
|
|
|
## Future Extensions
|
|
|
|
The package structure is designed to accommodate:
|
|
- Input components (ChatInput, forms, etc.)
|
|
- Layout helpers
|
|
- Data visualization components
|
|
- Utility functions
|
|
- Theme and styling extensions
|
|
|
|
## Development Guidelines
|
|
|
|
When adding new components:
|
|
1. Consider which submodule they belong in
|
|
2. Maintain full typing support
|
|
3. Provide both generic and inheritance-based usage patterns where applicable
|
|
4. Include proper async/await support where needed |