reorg

2026-06-16 23:39:45 -05:00
parent 8ada18b7fd
commit c8906cef7b
5 changed files with 269 additions and 0 deletions
@@ -0,0 +1,349 @@
+---
+name: nicegui-ui-customization
+description: Style, customize, and build interactive UIs in a production-ready NiceGUI app.
+---
+
+# NiceGUI UI Customization & Component Patterns
+
+Customize, style, and build interactive user interfaces in a production-ready NiceGUI application. This skill covers component architecture, styling systems, event-driven interactions, and practical troubleshooting for production deployments.
+
+## Goal
+
+Create a well-architected, responsive, accessible UI that:
+- Separates structure (Python layout) from cosmetics (CSS styling)
+- Handles user interactions via event-driven patterns, not polling
+- Composes reusable components with clear responsibilities
+- Integrates custom styling and assets cleanly
+- Troubleshoots common failures (race conditions, asset caching, upload errors)
+
+## Project Structure & Conceptual Boundaries
+
+This skill assumes a project organized with clear, modular boundaries:
+
+```text
+src/app/
+├─ ui/
+│  ├─ pages/                 # Page-level UI modules (route handlers)
+│  │  ├─ __init__.py
+│  │  ├─ home.py
+│  │  ├─ dashboard.py
+│  │  └─ about.py
+│  ├─ components/            # Reusable presentation components
+│  │  ├─ __init__.py
+│  │  ├─ nav.py
+│  │  ├─ card_section.py
+│  │  └─ form_section.py
+│  └─ static/                # Static assets (CSS, JS, images)
+│     ├─ css/
+│     │  ├─ base.css
+│     │  ├─ theme.css
+│     │  └─ components.css
+│     ├─ js/
+│     └─ images/
+├─ services/                 # Business logic layer
+│  ├─ __init__.py
+│  ├─ file_service.py
+│  ├─ user_service.py
+│  └─ ...
+├─ api/                      # HTTP endpoints
+│  ├─ __init__.py
+│  ├─ health.py
+│  └─ routes.py
+├─ bootstrap.py              # App composition, CSS/asset setup
+├─ config.py                 # Settings and configuration
+└─ ...
+```
+
+**Key boundaries**:
+- **`ui/pages/`**: Route-level adapters that call `services/`
+- **`ui/components/`**: Reusable presentation components (no business logic)
+- **`ui/static/`**: Assets loaded at startup in `bootstrap.py`
+- **`services/`**: Business logic (independent of UI)
+- **`api/`**: HTTP endpoints
+
+**Dependency flow**: `pages/` → `components/` + `services/` (no reverse imports)
+
+---
+
+## UI Component Patterns
+
+Components are the building blocks of reusable UI. They live in `ui/components/` and are consumed by pages in `ui/pages/`. Each component maps to [NiceGUI elements](https://nicegui.io/documentation/element), which expose a consistent API for structure, styling, and event handling.
+
+### Reusable Components
+
+Extract to `ui/components/` when patterns repeat across pages. Keep in-page layouts unique to that page.
+
+```python
+# ui/components/card_section.py
+def card_section(title: str, content: str) -> ui.card:
+    with ui.card().classes("w-full max-w-md") as card:
+        ui.label(title).classes("text-lg font-bold")
+        ui.label(content).classes("text-gray-600")
+    return card
+```
+
+### Layout Patterns
+
+Use Tailwind for all structural styling. Reserve `.style()` for computed values.
+
+```python
+with ui.column().classes("w-full"):
+    with ui.row().classes("w-full gap-4 flex-wrap sm:flex-nowrap"):
+        ui.card().classes("flex-1 min-w-64")
+        ui.card().classes("flex-1 min-w-64")
+```
+
+### State Management
+
+Use [bindable dataclasses](https://nicegui.io/documentation/section_binding_properties) for automatic two-way binding.
+
+```python
+from nicegui import binding, ui
+from dataclasses import field
+
+@binding.bindable_dataclass
+class PageState:
+    selected_id: int | None = None
+    items: list = field(default_factory=list)
+
+state = PageState()
+detail_label = ui.label().bind_text_from(state, 'selected_id')
+
+def on_select(item_id):
+    state.selected_id = item_id  # Auto-updates UI
+
+state.bind_on_change(lambda: load_detail(), 'selected_id')
+```
+
+---
+
+## Styling
+
+Use Tailwind for all styling. Use breakpoint prefixes (`sm:`, `md:`, `lg:`) for responsive design.
+
+### Custom CSS Injection ⚠️ Avoid This Pattern
+
+**Avoid injecting custom CSS** via `ui.add_css()` at app startup. Custom CSS injection creates maintenance burden, breaks IDE autocomplete, and makes styling harder to reason about. Instead:
+
+**✅ Prefer these approaches**:
+1. **Use [Tailwind utility classes](https://tailwindcss.com/docs/utility-first)** — covers 95% of styling needs with zero CSS overhead.
+   ```python
+   with ui.column().classes("w-full bg-gradient-to-br from-gray-100 to-gray-200"):
+       with ui.card().classes("rounded-lg border border-gray-300 shadow-md hover:shadow-lg transition-shadow"):
+           ui.label("Content")
+   ```
+
+2. **Use [Quasar props](https://quasar.dev/vue-components)** — high-level component theming built into NiceGUI elements.
+   ```python
+   ui.button("Submit").props("color=primary size=lg")
+   ```
+
+3. **Extract reusable components** — encapsulate styling patterns in Python functions rather than CSS classes.
+   ```python
+   def styled_card(title: str, content: str) -> ui.card:
+       with ui.card().classes("rounded-lg border border-gray-300 shadow-md") as card:
+           ui.label(title).classes("text-lg font-bold")
+           ui.label(content).classes("text-gray-600")
+       return card
+   ```
+
+**If you absolutely must inject CSS** (rare edge cases only):
+- Store CSS in `src/app/static/css/` files
+- Load via `ui.add_css(open('src/app/static/css/custom.css').read())` in `bootstrap.py`
+- Keep injected CSS minimal and well-documented
+- Avoid hardcoding colors or spacing; use CSS variables instead
+
+### Static Assets
+
+Load CSS files at app startup in `bootstrap.py`:
+```python
+from fastapi.staticfiles import StaticFiles
+
+app.mount("/static", StaticFiles(directory="src/app/static"), name="static")
+ui.add_css(open('src/app/static/css/base.css').read())
+```
+
+Use CSS variables for design tokens:
+```css
+:root {
+    --color-primary: #3b82f6;
+    --spacing-unit: 1rem;
+}
+```
+
+### JS Injection (Rare)
+
+Use `ui.run_javascript()` only for unsupported interactions. Prefer [NiceGUI APIs](https://nicegui.io/documentation/section_action_events) first.
+
+---
+
+## Event-Driven Patterns
+
+NiceGUI provides event-driven APIs for [actions and events](https://nicegui.io/documentation/section_action_events). This section covers common patterns: file uploads, form submissions, WebSocket/SSE for real-time updates, and background tasks.
+
+### File Upload
+
+Validate and notify; delegate storage to service layer.
+
+```python
+async def handle_upload(e: ui.events.UploadEventArguments):
+    try:
+        if e.size > 10 * 1024 * 1024:
+            raise ValueError("File too large")
+        if not e.name.endswith('.pdf'):
+            raise ValueError("Only PDF allowed")
+        await file_service.store(e.content.read(), e.name)
+        ui.notify(f"Uploaded: {e.name}", type="positive")
+    except ValueError as err:
+        ui.notify(str(err), type="negative")
+
+ui.upload(on_upload=handle_upload, auto_upload=True)
+```
+
+### Form Submission
+
+Bind form inputs to dataclass; validate in service.
+
+```python
+@binding.bindable_dataclass
+class FormData:
+    name: str = ""
+    email: str = ""
+
+data = FormData()
+ui.input("Name").bind_value(data, 'name')
+ui.input("Email").bind_value(data, 'email')
+
+async def on_submit():
+    try:
+        await user_service.create_user(name=data.name, email=data.email)
+        ui.notify("User created", type="positive")
+        data.name = data.email = ""
+    except ValueError as err:
+        ui.notify(str(err), type="negative")
+
+ui.button("Submit").on_click(on_submit)
+```
+
+### Real-Time Updates (WebSocket / SSE)
+
+For streaming updates, use [SSE](https://fastapi.tiangolo.com/advanced/server-sent-events/) (one-way) or [WebSocket](https://fastapi.tiangolo.com/advanced/websockets/) (bidirectional).
+
+```python
+# api/events.py
+@app.get("/events/status")
+async def status_stream():
+    async def gen():
+        while True:
+            yield f"data: {await get_status()}\\n\\n"
+            await asyncio.sleep(1)
+    return StreamingResponse(gen(), media_type="text/event-stream")
+
+# Page
+status_label = ui.label()
+async def listen():
+    async with aiohttp.ClientSession() as s:
+        async with s.get("/api/events/status") as r:
+            async for line in r.content:
+                if line.startswith(b"data:"):
+                    status_label.set_text(line.decode().replace("data:", "").strip())
+
+ui.timer(0.1, lambda: asyncio.create_task(listen()))
+```
+
+### Background Tasks
+
+Delegate long-running work to background tasks; signal UI via polling or WebSocket.
+
+```python
+# API
+@app.post("/process")
+async def process(background_tasks: BackgroundTasks):
+    background_tasks.add_task(long_job)
+    return {"status": "processing"}
+
+# Page
+async def on_start():
+    await client.post("/api/process")
+    ui.notify("Started")
+
+async def check():
+    status = await client.get("/api/process/status")
+    if status == "done":
+        ui.notify("Complete", type="positive")
+
+ui.button("Start").on_click(on_start)
+ui.timer(1, check)
+```
+
+### Reactive Refresh
+
+Use `@ui.refreshable` with explicit refresh triggers; avoid polling everything.
+
+```python
+@ui.refreshable
+async def item_list():
+    items = await service.list()
+    for item in items:
+        ui.label(item.name)
+
+ui.button("Refresh").on_click(lambda: item_list.refresh())
+```
+
+---
+
+## Advanced Interactions
+
+### Dialogs
+
+```python
+dialog = ui.dialog()
+
+async def show_confirm():
+    with dialog:
+        ui.label("Are you sure?")
+        ui.button("Yes").on_click(lambda: (confirm_action(), dialog.close()))
+        ui.button("No").on_click(dialog.close)
+    dialog.open()
+
+ui.button("Delete").on_click(show_confirm)
+```
+
+### Progress
+
+```python
+progress = ui.linear_progress(value=0).classes("w-full")
+
+async def handle_upload(e):
+    for chunk in read_chunks(e.content):
+        progress.set_value(uploaded / total)
+    ui.notify("Complete", type="positive")
+```
+
+### Drag & Drop
+
+Use [Quasar q-sortable](https://quasar.dev/vue-components/sortable) for native drag-and-drop support via `.props()`.
+
+---
+
+## Troubleshooting
+
+### Upload Validation & Errors
+- Validate file size/extension before storage
+- Catch exceptions and emit `ui.notify()` with type "negative"
+- Log errors for debugging
+
+### Race Conditions
+- Serialize updates: `await service.get_data()` before UI update
+- Avoid multiple timers on same component
+- Use `button.enabled = False/True` to prevent duplicate submissions
+
+### Asset Caching
+- Inject CSS in `bootstrap.py` at startup, not per-page
+- Clear browser cache (Ctrl+Shift+Del) or use cache-busting query params: `?v=hash`
+- Verify `/static/` mount path and nginx proxy rewrites
+
+### Navigation & State
+- Don't store state in globals; keep in `services/` or request-scoped
+- Use `ui.navigate.to()` to switch pages
+- Reload data in destination page's `@ui.page()` decorator