# 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