WIP components (as built)

docs/components/221-prompt-composer.md

@@ -0,0 +1,40 @@
+# 221 PromptComposer 提示编辑器
+
+## 用途
+
+多行输入；Enter 发送、Shift+Enter 换行可配置；输入法组合期间不发送；附件与工具插槽。
+
+## 最小示例
+
+```go
+var prompt string
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.PromptComposer(c, &prompt, mujica.PromptComposerOptions{Placeholder: "Ask the herald"})
+	if r.Submitted() {
+		fmt.Println("send", prompt)
+		prompt = ""
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`value` 为调用方持有的文本指针。`Placeholder`、`Label` 配置占位与名称；`CmdEnterSends=false` 使用 Enter 发送；`Composing=false`，调用方在组合输入时设为 true；`MaxHeight=0` 使用 200 DIP。`Attachments`、`Tools`、`Actions` 为内容插槽；`Disabled=false`。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+InputResult.Changed() 表示文本编辑；Submitted() 表示发送请求；Input 暴露编辑器。
+
+## 键盘操作
+
+Enter 发送，Shift+Enter 换行；CmdEnterSends 下使用 Command/Ctrl+Enter；组合保护期间 Enter 留给输入法。
+
+## 限制
+
+MyGo v0.2.10 的 ui/input.go:688–708 将组合事件直接送到私有编辑器，公开 HandleInput 无法观察组合状态。自动检测组合输入仍需上游 API；调用方须设置 Composing。

docs/components/222-attachment-chip.md

@@ -0,0 +1,38 @@
+# 222 AttachmentChip 附件标签
+
+## 用途
+
+附件名、类型、大小、上传进度、移除；失败重试。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.AttachmentChip(c, mujica.Attachment{Name: "guests.csv", Size: 4096, Uploading: true, Progress: 0.4})
+	if r.Removed() {
+		fmt.Println("cancel the upload")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`Attachment.Name` 必填；`Type` 为 MIME 类型，空值按扩展名选择图标；`Size` 为非负字节数；`Uploading` 默认 false，`Progress` 为 0–1；`Err` 表示上传失败。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+Removed() 表示移除；Retried() 表示重试。
+
+## 键盘操作
+
+Tab 到移除与重试；Enter、Space 激活。
+
+## 限制
+
+上传由调用方执行，组件只展示进度与结果。

docs/components/223-paste-image-preview.md

@@ -0,0 +1,39 @@
+# 223 PasteImagePreview 图片预览
+
+## 用途
+
+粘贴或拖入图片的预览缩略图；移除。
+
+## 最小示例
+
+```go
+pic := ui.MustParseSVG([]byte(`<svg xmlns="http://www.w3.org/2000/svg" width="4" height="3"/>`))
+images := []mujica.PastedImage{{ID: "p1", Source: pic, Name: "screenshot"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if id, ok := mujica.PasteImagePreview(c, images).Removed(); ok {
+		fmt.Println("remove", id)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`images` 为调用方解码的缩略图列表。每项 `ID` 为唯一稳定标识，`Source` 为必填图片，`Name` 为操作名称；缩略图边长为 72 DIP。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+Removed() 返回待移除的稳定 ID 与事件标志。
+
+## 键盘操作
+
+Tab 到移除按钮；Enter、Space 移除。
+
+## 限制
+
+粘贴和拖入的图片解码、获取及去重由调用方完成。MyGo ui/headless.go:377–380 仅提供文本剪贴板；ui/drop.go:11 返回文件路径，原生图片剪贴板接口仍需上游扩展。

docs/components/224-drag-drop-overlay.md

@@ -0,0 +1,41 @@
+# 224 DragDropOverlay 拖放遮罩
+
+## 用途
+
+拖入文件时的全区域遮罩与提示；类型检查回调。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	images := func(path string) bool { return strings.HasSuffix(path, ".png") }
+	r := mujica.DragDropOverlay(c, mujica.DragDropOverlayOptions{Accept: images}, func() {
+		ui.Text(c, "Drag images into the chat")
+	})
+	for _, path := range r.Accepted() {
+		fmt.Println("attach", path)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`content` 必填；`Hint` 默认“松开以添加文件”；`Accept` 接收路径并返回类型检查结果，nil 接受全部。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+Accepted() 与 Rejected() 返回本帧接受和拒绝的文件路径。
+
+## 键盘操作
+
+内容中的操作按其自身键盘规则访问；文件拖入由操作系统驱动。
+
+## 限制
+
+读取文件与上传由调用方完成。MyGo ui/headless.go:93–163 的 Tester 通过平台事件驱动，公开接口未提供外部文件拖放注入；类型检查与遮罩分别测试。

docs/components/225-voice-input-button.md

@@ -0,0 +1,38 @@
+# 225 VoiceInputButton 语音输入按钮
+
+## 用途
+
+录音开始与停止；录音时长；权限失败提示；录音由调用方实现。
+
+## 最小示例
+
+```go
+var rec mujica.VoiceInputOptions
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.VoiceInputButton(c, rec).Changed() {
+		rec = mujica.VoiceInputOptions{Recording: !rec.Recording, Started: time.Now()}
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`Recording=false`；录音时 `Started` 必填；`Denied=false`，表示权限失败；`Disabled=false`。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+ChoiceResult.Changed() 表示开始、停止或重试录音请求。
+
+## 键盘操作
+
+Tab 到按钮；Enter、Space 开始或停止。
+
+## 限制
+
+录音与权限请求由调用方实现。

docs/components/226-voice-waveform.md

@@ -0,0 +1,36 @@
+# 226 VoiceWaveform 输入波形
+
+## 用途
+
+输入电平波形；静音提示。
+
+## 最小示例
+
+```go
+levels := []float32{0.2, 0.6, 0.9, 0.4, 0.1}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.VoiceWaveform(c, levels, mujica.VoiceWaveformOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`levels` 为 0–1 的电平样本，最新样本放在末尾。`Silence=0` 使用 0.05；`SilentFor=0` 使用 20 个样本；`Width=0` 使用 200 DIP。
+
+## 状态
+
+展示由输入数据驱动；边界值与警告状态带文字说明。
+
+## 事件
+
+展示组件，样本变化由调用方更新。
+
+## 键盘操作
+
+展示组件，沿用外层 Tab 顺序。
+
+## 限制
+
+电平采集由调用方提供；只绘制适合宽度的最新样本。

docs/components/227-slash-command-menu.md

@@ -0,0 +1,40 @@
+# 227 SlashCommandMenu 斜杠命令菜单
+
+## 用途
+
+输入“/”弹出命令；筛选；方向键选择；Tab 补全。
+
+## 最小示例
+
+```go
+var prompt string
+commands := []mujica.SlashCommand{{Name: "summarize", Description: "Summarize the thread"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	composer := mujica.PromptComposer(c, &prompt, mujica.PromptComposerOptions{})
+	if cmd, ok := mujica.SlashCommandMenu(c, composer, &prompt, commands).Chosen(); ok {
+		fmt.Println("run", cmd.Name)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`composer` 为本帧构建的 PromptComposer 结果；`value` 为同一文本指针；`commands` 每项 `Name` 为必填单词，`Description` 为调用方说明。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+Chosen() 返回选中的命令；Tab 补全文本，Enter 选择命令。
+
+## 键盘操作
+
+编辑器内 Up/Down 选择，Enter 选中，Tab 补全，Escape 关闭。
+
+## 限制
+
+菜单按可见行虚拟化；筛选在查询或命令变化时更新。

docs/components/228-context-mention-menu.md

@@ -0,0 +1,44 @@
+# 228 ContextMentionMenu 上下文提及菜单
+
+## 用途
+
+输入“@”选择文件、文档、网页等上下文；分组；异步结果。
+
+## 最小示例
+
+```go
+var prompt string
+var found []mujica.ContextItem
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	composer := mujica.PromptComposer(c, &prompt, mujica.PromptComposerOptions{})
+	r := mujica.ContextMentionMenu(c, composer, &prompt, found, mujica.ContextMentionOptions{})
+	if r.QueryChanged() {
+		found = []mujica.ContextItem{{ID: "f1", Label: r.Query() + ".md", Kind: mujica.ContextFile}}
+	}
+	if item, ok := r.Chosen(); ok {
+		fmt.Println("attach", item.ID)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`composer` 与 `value` 关联当前编辑器；`items` 每项 `ID`、`Label` 必填，`Detail` 可选，`Kind` 为 ContextFile、ContextDoc 或 ContextWeb；`Loading=false`。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+QueryChanged() 请求新查询；Query() 返回查询文本；Chosen() 返回上下文并移除尾部提及文字。
+
+## 键盘操作
+
+编辑器内 Up/Down 选择，Enter 或 Tab 附加，Escape 关闭。
+
+## 限制
+
+异步结果由调用方提供并调用 c.Invalidate()，调用方负责淘汰过期请求。

docs/components/229-context-chips.md

@@ -0,0 +1,38 @@
+# 229 ContextChips 上下文标签
+
+## 用途
+
+已附加上下文列表；移除；溢出折叠。
+
+## 最小示例
+
+```go
+items := []mujica.ContextItem{{ID: "f1", Label: "guests.csv", Kind: mujica.ContextFile}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if id, ok := mujica.ContextChips(c, items, mujica.ContextChipsOptions{}).Removed(); ok {
+		fmt.Println("detach", id)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`items` 为已附加上下文，`ID`、`Label` 必填，`Kind` 指定图标；`Max=0` 默认显示 4 项，超出时可展开。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+Removed() 返回待移除 ID；展开与折叠保留在组件状态。
+
+## 键盘操作
+
+Tab 到移除与展开；Enter、Space 激活。
+
+## 限制
+
+上下文文件内容由调用方管理。

docs/components/230-model-selector.md

@@ -0,0 +1,39 @@
+# 230 ModelSelector 模型选择器
+
+## 用途
+
+模型列表；能力标签与上下文长度；不可用项说明。
+
+## 最小示例
+
+```go
+model := "herald"
+models := []mujica.ModelOption{{ID: "herald", Name: "Herald 2", Capabilities: []string{"Vision"}, ContextTokens: 200000}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ModelSelector(c, &model, models, mujica.ModelSelectorOptions{}).Changed() {
+		fmt.Println("model", model)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`value` 为模型 ID 指针；`models` 每项 `ID`、`Name` 必填，`Capabilities` 为能力标签，`ContextTokens=0` 隐藏容量；`Unavailable` 提供不可用原因。`Label` 默认“模型”，`Disabled=false`。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+ChoiceResult.Changed() 表示模型 ID 已改变。
+
+## 键盘操作
+
+Tab 到选择器；Up/Down、Home/End 选择，Enter/Space 确认，Escape 关闭。
+
+## 限制
+
+模型服务与可用性由调用方提供。

docs/components/231-mode-selector.md

@@ -0,0 +1,38 @@
+# 231 ModeSelector 模式选择器
+
+## 用途
+
+对话、搜索、深度研究、Agent 模式切换。
+
+## 最小示例
+
+```go
+mode := mujica.ModeChat
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ModeSelector(c, &mode, mujica.ModeSelectorOptions{}).Changed() {
+		fmt.Println("mode", mode)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`mode` 指向 ModeChat、ModeSearch、ModeResearch 或 ModeAgent；`IconsOnly=false` 保留文字；`Disabled=false`。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+ChoiceResult.Changed() 表示模式已改变。
+
+## 键盘操作
+
+Tab 进入模式组；Left/Right 切换模式。
+
+## 限制
+
+模式执行逻辑由调用方实现。

docs/components/232-tool-toggle-menu.md

@@ -0,0 +1,39 @@
+# 232 ToolToggleMenu 工具开关菜单
+
+## 用途
+
+联网、代码执行等工具开关；需授权项标记。
+
+## 最小示例
+
+```go
+web := true
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	tools := []mujica.ToolItem{{ID: "web", Label: "Web search", On: &web}}
+	if id, ok := mujica.ToolToggleMenu(c, tools).Changed(); ok {
+		fmt.Println("toggled", id)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`tools` 每项 `ID`、`On` 必填；`Label`、`Description` 由调用方提供；`NeedsAuth=false`；需要授权时由 `Authorized` 控制开关可用性。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+Changed() 返回切换工具 ID；Authorize() 返回授权请求 ID。
+
+## 键盘操作
+
+Tab 到菜单按钮；Enter/Space 打开；Tab 到开关与授权；Escape 关闭。
+
+## 限制
+
+授权与工具执行由调用方完成。

docs/components/233-parameter-panel.md

@@ -0,0 +1,37 @@
+# 233 ParameterPanel 参数面板
+
+## 用途
+
+温度、Top-p、最大长度等参数；范围与默认值；重置。
+
+## 最小示例
+
+```go
+temperature := 1.0
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	params := []mujica.ModelParam{{Label: "Temperature", Value: &temperature, Min: 0, Max: 2, Step: 0.1, Default: 1}}
+	mujica.ParameterPanel(c, params)
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`params` 每项 `Label`、`Value` 必填；`Min < Max`、`Step > 0`；`Default` 与当前值须为有限范围内数值，且位于 Min 起算的 Step 网格；范围与默认值显示在滑轨下。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+ChoiceResult.Changed() 表示参数或默认值重置改变了值。
+
+## 键盘操作
+
+Tab 到滑块与重置；方向键按 Step 调整，Home/End 到范围端点；Enter/Space 重置。
+
+## 限制
+
+参数校验失败 panic，数字步进复用 Slider 与 NumberInput 的步长网格。

docs/components/234-token-counter.md

@@ -0,0 +1,35 @@
+# 234 TokenCounter Token计数
+
+## 用途
+
+当前输入 token 数与上限；估算值由调用方提供。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.TokenCounter(c, 1234, 8000)
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`used` 为调用方估算的非负 token 数；`limit` 为正数；达到 90% 时警告，超过上限时显示超额。
+
+## 状态
+
+展示由输入数据驱动；边界值与警告状态带文字说明。
+
+## 事件
+
+展示组件，调用方更新估算值。
+
+## 键盘操作
+
+展示组件，沿用外层 Tab 顺序。
+
+## 限制
+
+token 分词与模型计算由调用方完成。

docs/components/235-context-window-meter.md

@@ -0,0 +1,36 @@
+# 235 ContextWindowMeter 上下文容量
+
+## 用途
+
+上下文使用率条；分段（系统、历史、附件）；阈值警告。
+
+## 最小示例
+
+```go
+segments := []mujica.ContextSegment{{Label: "System", Tokens: 1200}, {Label: "History", Tokens: 58000}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ContextWindowMeter(c, segments, 128000, mujica.ContextWindowMeterOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`segments` 每项 `Label` 必填、`Tokens` 非负；`limit` 为正数；`Warn=0` 默认阈值 0.8，允许配置 0–1。
+
+## 状态
+
+展示由输入数据驱动；边界值与警告状态带文字说明。
+
+## 事件
+
+展示组件，调用方更新各段用量。
+
+## 键盘操作
+
+展示组件，沿用外层 Tab 顺序。
+
+## 限制
+
+上下文数据由调用方统计，分段同时提供文字与图形标记。

docs/components/236-send-button.md

@@ -0,0 +1,39 @@
+# 236 SendButton 发送按钮
+
+## 用途
+
+发送与停止两态；禁用条件；快捷键提示。
+
+## 最小示例
+
+```go
+streaming := false
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.SendButton(c, mujica.SendButtonOptions{Streaming: streaming, Shortcut: "Enter"})
+	if r.Sent() || r.Stopped() {
+		streaming = r.Sent()
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`Streaming=false` 显示发送；true 显示停止；`Disabled=false`，禁用发送时停止仍可用；`Shortcut` 仅展示在提示中。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+Sent() 表示发送请求；Stopped() 表示停止请求。
+
+## 键盘操作
+
+Tab 到按钮；Enter、Space 激活；快捷键提示由调用方绑定。
+
+## 限制
+
+生成和停止逻辑由调用方实现。

docs/components/237-citation-badge.md

@@ -0,0 +1,39 @@
+# 237 CitationBadge 引用编号
+
+## 用途
+
+行内引用编号；悬停预览来源；点击定位来源。
+
+## 最小示例
+
+```go
+var cites mujica.CitationState
+src := mujica.Source{Title: "The Palace of Versailles", URL: "https://example.com/versailles"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.CitationBadge(c, 1, src, &cites).Changed() {
+		fmt.Println("show source", cites.Active)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`n` 为从 1 开始的引用编号；`src.Title`、`src.URL` 必填；`st` 为与来源卡片共享的 CitationState；`Active=0` 表示尚未选中。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+每次点击或键盘激活触发 ChoiceResult.Changed() 并定位来源；重复激活同一引用也会重新定位。
+
+## 键盘操作
+
+Tab 到引用；Enter、Space 定位；悬停或键盘焦点 500 毫秒后预览；Escape 关闭预览。
+
+## 限制
+
+编号按调用方引用顺序映射；预览内容来自调用方。

docs/components/238-source-card.md

@@ -0,0 +1,39 @@
+# 238 SourceCard 来源卡片
+
+## 用途
+
+来源标题、站点、摘要、时间；打开回调。
+
+## 最小示例
+
+```go
+var cites mujica.CitationState
+src := mujica.Source{Title: "Hall of Mirrors", URL: "https://example.org/hall", Snippet: "Seventeen arches."}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.SourceCard(c, 1, src, &cites).Clicked() {
+		fmt.Println("open", src.URL)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`n` 为引用编号；`src.Title`、`src.URL` 必填，`Site`、`Snippet`、`Published` 可选；`st` 与正文引用共享。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+Element.Clicked() 表示打开来源请求。
+
+## 键盘操作
+
+Tab 到卡片；Enter、Space 请求打开。
+
+## 限制
+
+打开 URL 由调用方处理；组件返回事件。

docs/components/239-sources-panel.md

@@ -0,0 +1,39 @@
+# 239 SourcesPanel 来源面板
+
+## 用途
+
+来源列表；按引用顺序；与正文引用联动高亮。
+
+## 最小示例
+
+```go
+var cites mujica.CitationState
+sources := []mujica.Source{{Title: "Hall of Mirrors", URL: "https://example.org/hall"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if n, ok := mujica.SourcesPanel(c, sources, &cites).Opened(); ok {
+		fmt.Println("open", sources[n-1].URL)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`sources` 按引用顺序提供；`st.Active` 为 0 或列表内的引用编号；外层容器提供高度。
+
+## 状态
+
+默认、悬停、键盘焦点与祖先禁用；业务状态由调用方提供。
+
+## 事件
+
+Opened() 返回从 1 开始的来源编号。
+
+## 键盘操作
+
+Tab 到可见来源；Enter、Space 请求打开；滚轮滚动；Active 变化定位来源。
+
+## 限制
+
+使用虚拟列表，只构建可见来源；调用方保证引用编号和来源顺序一致。

docs/components/240-search-progress.md

@@ -0,0 +1,36 @@
+# 240 SearchProgress 搜索进度
+
+## 用途
+
+搜索中关键词与已读来源数；阶段列表；完成后折叠。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	stages := []mujica.SearchStage{{Label: "Searching the web", Done: true}, {Label: "Reading sources"}}
+	mujica.SearchProgress(c, mujica.SearchProgressOptions{Query: "Versailles", Read: 3, Total: 8, Stages: stages})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`Query` 必填；`Read`、`Total` 满足 0 ≤ Read ≤ Total；`Stages` 每项提供 `Label` 与 `Done`；`Done=false`，完成时自动折叠一次。
+
+## 状态
+
+搜索中展开，完成后自动折叠；Done 从 true 切换为 false 时展开下一次搜索；支持键盘焦点与祖先禁用。
+
+## 事件
+
+ChoiceResult.Changed() 表示用户展开或折叠。
+
+## 键盘操作
+
+Tab 到折叠标题；Enter、Space 展开或收起。
+
+## 限制
+
+网络搜索由调用方执行，阶段与来源数量由调用方更新。