# Kokage UI

このプロジェクトは、[このページ](https://zenn.dev/livetoon/articles/04dccf642d324c)のアイデアをベースにして、FastAPIに簡単にUIを追加できるpythonパッケージです。
FastAPIとhtmxを組み合わせて、簡単にUIを作成できるようにすることを目的としています。

## 開発環境

- Python 3.13
- uv

### 開発環境構築

```bash
uv sync --extra dev
```

### テスト実行

```bash
uv run pytest tests/ -v
```

### exampleの実行方法

```bash
uv run uvicorn examples.hello:app --reload
uv run uvicorn examples.todo:app --reload
uv run uvicorn examples.dashboard:app --reload
```

## パッケージ構成

```
src/kokage_ui/
├── core.py          # KokageUI — FastAPI統合（page/fragment/crud/validateデコレータ）
├── page.py          # Page — <!DOCTYPE html>ドキュメント生成
├── elements.py      # Component基底クラス + 50以上のHTML要素クラス
├── components.py    # DaisyUIコンポーネント（Card, NavBar, Modal, Tabs等 25+）
├── models.py        # Pydantic→UI自動生成（ModelForm, ModelTable, ModelDetail）
├── crud.py          # CRUDRouter, Storage ABC, InMemoryStorage, Pagination
├── storage.py       # SQLModelStorage（非同期SQL永続化）
├── datagrid.py      # DataGrid（ソート/フィルタ/一括操作/CSV出力）
├── htmx.py          # htmxパターン（AutoRefresh, SearchFilter, InfiniteScroll等）
├── forms.py         # MultiStepForm（マルチステップフォーム）
├── auth.py          # 認証UI（LoginForm, RegisterForm, UserMenu, RoleGuard, protected）
├── theme.py         # テーマ切替（DarkModeToggle, ThemeSwitcher）
├── notifications.py # リアルタイム通知（Notifier, NotificationStream — SSE）
├── admin.py         # 管理画面自動生成（AdminSite, ModelAdmin）
├── charts.py        # Chart.jsラッパー
├── code.py          # CodeBlock（シンタックスハイライト）
├── markdown.py      # Markdownレンダラー
├── toolbar.py       # 開発ツールバー（DevToolbarMiddleware）
├── cli.py           # CLIスキャフォールディングツール
├── templates.py     # CLIテンプレート文字列
└── static/htmx.min.js
```

## 設計上の注意

- `cls` → `class`, `hx_get` → `hx-get`（アンダースコア→ハイフン変換）
- 低レベル `Button` と高レベル `DaisyButton` が共存
- `fragment` デコレータはデフォルト `htmx_only=True`
- htmxはローカルバンドル、DaisyUI/TailwindはCDN
- XSS保護: markupsafe.escape()
- models.pyはHTML validation属性を直接`<input>`に渡すためDaisyInputを使わない

## Browser Automation

Use `agent-browser` for web automation. Run `agent-browser --help` for all commands.

Core workflow:
1. `agent-browser open <url>` - Navigate to page
2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
4. Re-snapshot after page change
