# 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
chat_input.py        # ChatInput component (to be moved into package)
```

## 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. ChatInput Component
A textarea component optimized for chat interfaces:
- Enter to send message
- Shift+Enter for new line
- Callback-based message handling
- Currently in `chat_input.py`, should be moved to package structure

## Import Convention

The package uses a submodule structure to organize different types of extensions:

```python
from niceguiex.async_elements import AsyncColumn, AsyncCard
from chat_input import ChatInput  # To be: from niceguiex.inputs import ChatInput
```

## 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