# 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/
├── __init__.py          # 公開API（全re-export）
├── 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+）
├── htmx.py              # htmxパターン（AutoRefresh, SearchFilter, InfiniteScroll等）
├── models.py            # Pydantic→UI自動生成（ModelForm, ModelTable, ModelDetail）
│
├── fields/              # フィールドアノテーション & 専用コンポーネント
│   ├── media.py         # MediaField, VideoPlayer, AudioPlayer, ImageGallery, MediaCard
│   ├── richtext.py      # RichTextField, RichTextEditor
│   ├── repeater.py      # RepeaterField, RepeaterInput
│   └── sortable.py      # SortableList
│
├── data/                # CRUD・データ永続化
│   ├── crud.py          # CRUDRouter, Storage, InMemoryStorage, Pagination
│   ├── storage.py       # SQLModelStorage
│   └── datagrid.py      # DataGrid, DataGridState, ColumnFilter
│
├── features/            # 機能拡張
│   ├── forms.py         # MultiStepForm, FormStep
│   ├── auth.py          # 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レンダラー
│
├── dev/                 # 開発ツール
│   ├── testing.py       # HTMLAssertions, ResponseAssertions等
│   ├── toolbar.py       # DevToolbarMiddleware
│   ├── cli.py           # kokage init/add
│   └── 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
