NiceGUIEx/CLAUDE.md

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:

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