Merge ae66cd6d621c16060 (as built)

docs/components/442-stat-card.md

@@ -0,0 +1,39 @@
+# 442 StatCard · 统计卡片
+
+## 用途
+
+展示调用方统计值、变化率和迷你趋势图。
+
+## 最小示例
+
+```go
+value := "12,480"
+opts := mujica.StatCardOptions{Label: "Requests", Change: 0.12, HasChange: true, Trend: []float64{3, 5, 4, 8}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.StatCard(c, value, opts).Changed() {
+		fmt.Println("retry")
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+Label 必填；Change 是相对变化；HasChange 开启变化说明；LowerIsBetter 反转好坏；Trend 为趋势值；Status、Error 控制加载与错误。
+
+## 状态
+
+值与变化率、趋势、加载、失败、父级禁用。
+
+## 事件
+
+Changed() 表示重试。
+
+## 键盘操作
+
+Tab 聚焦趋势或重试；方向键读取数据；Enter 激活重试。
+
+## 限制
+
+卡片最小高度 116 DIP，随桌面文本缩放增长；统计值由调用方计算。

docs/components/443-alert-list.md

@@ -0,0 +1,42 @@
+# 443 AlertList · 告警列表
+
+## 用途
+
+按级别、来源与发生时间展示告警；报告确认和静默请求。
+
+## 最小示例
+
+```go
+alerts := []mujica.AlertItem{{ID: "cpu", Title: "CPU usage high", Level: mujica.AlertWarning, Source: "worker", At: time.Date(2026, 10, 5, 9, 0, 0, 0, time.UTC)}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.AlertList(c, alerts, mujica.AlertListOptions{})
+	if r.Ack != "" {
+		fmt.Println("ack", r.Ack)
+	}
+	if r.Silence != "" {
+		fmt.Println("silence", r.Silence)
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+MaxHeight 为列表最大高度，默认 360 DIP；Disabled 禁用操作。AlertItem.ID 唯一，Title 必填，Level 为有效枚举；Acked、Silence 展示处理状态。
+
+## 状态
+
+未处理、已确认、静默中、空列表、禁用。
+
+## 事件
+
+Ack、Silence 返回告警 ID；调用方更新 Acked 或 Silence。
+
+## 键盘操作
+
+Tab 聚焦按钮；Enter 或 Space 激活。
+
+## 限制
+
+静默请求固定为一小时；告警数据由调用方管理。

docs/components/444-incident-card.md

@@ -0,0 +1,36 @@
+# 444 IncidentCard · 事件卡片
+
+## 用途
+
+展示事件标题、状态、影响与按时间排列的更新。
+
+## 最小示例
+
+```go
+incident := mujica.Incident{Title: "API latency", Status: mujica.IncidentMonitoring, Impact: mujica.ImpactMinor, Updates: []mujica.IncidentUpdate{{Status: mujica.IncidentIdentified, Text: "Slow query located"}, {Status: mujica.IncidentMonitoring, Text: "Recovery observed"}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.IncidentCard(c, incident)
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+Incident.Title 必填；Status、Impact 使用枚举；Started 与 Updates 的时间由调用方提供。
+
+## 状态
+
+调查中、已定位、观察中、已解决；四级影响。
+
+## 事件
+
+展示组件，调用方更新 Incident。
+
+## 键盘操作
+
+展示内容随调用方更新。
+
+## 限制
+
+时间线按输入顺序展示；调用方排序。

docs/components/445-uptime-bar.md

@@ -0,0 +1,42 @@
+# 445 UptimeBar · 可用性条
+
+## 用途
+
+按日展示可用性，以条高与文字区分状态。
+
+## 最小示例
+
+```go
+days := []mujica.UptimeDay{{Date: mujica.Date{Year: 2026, Month: 10, Day: 1}, Uptime: 1}, {Date: mujica.Date{Year: 2026, Month: 10, Day: 2}, Uptime: 0.91, Note: "Recovery"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.UptimeBar(c, days, mujica.UptimeBarOptions{Frame: mujica.ChartFrame{Label: "API uptime"}})
+	if r.Changed() {
+		fmt.Println("day", r.Point)
+	}
+	if r.Retried() {
+		fmt.Println("retry")
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+Frame.Label 必填；Frame.Height 默认 36 DIP；Frame.Status、Error 控制状态；Degraded 默认 0.999，Down 默认 0.95；Uptime 为 0 到 1，NaN 表示缺少数据。
+
+## 状态
+
+正常、降级、中断、缺测、空数据、加载、失败、父级禁用。
+
+## 事件
+
+Changed() 报告读取点变化；Point 为日期索引；Retried() 报告重试。
+
+## 键盘操作
+
+Tab 聚焦图；方向键逐日移动；Home、End 到边界；Escape 清除读取。
+
+## 限制
+
+大数据按像素列汇总；更新数据时提交新切片。

docs/components/446-service-status.md

@@ -0,0 +1,36 @@
+# 446 ServiceStatus · 服务状态
+
+## 用途
+
+展示服务正常、降级、中断和总体统计。
+
+## 最小示例
+
+```go
+services := []mujica.ServiceItem{{Name: "API", Health: mujica.ServiceOperational}, {Name: "Search", Health: mujica.ServiceDegraded, Note: "Slow queries"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ServiceStatus(c, services, mujica.ServiceStatusOptions{})
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+MaxHeight 默认 360 DIP；ServiceItem.Name 必填；Health 为有效枚举；Note 展示原因。
+
+## 状态
+
+正常、降级、中断、空列表；总体统计随数据更新。
+
+## 事件
+
+展示组件，调用方更新服务切片。
+
+## 键盘操作
+
+滚动列表浏览服务。
+
+## 限制
+
+状态来自调用方；每行使用图标和文字区分状态。更新服务数据时提交新切片。

docs/components/447-log-stream.md

@@ -0,0 +1,39 @@
+# 447 LogStream · 日志流
+
+## 用途
+
+展示实时 ANSI 日志，支持暂停、级别过滤与跟随末尾。
+
+## 最小示例
+
+```go
+lines := []mujica.LogLine{{Level: mujica.LogInfo, Text: "server ready"}, {Level: mujica.LogWarn, Text: "slow query"}}
+var state mujica.LogStreamState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.LogStream(c, lines, &state, mujica.LogStreamOptions{}).Changed() {
+		fmt.Println("filter changed")
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+Height 默认 320 DIP；Disabled 禁用；LogStreamState.Paused 控制暂停，MinLevel 指定最低级别。
+
+## 状态
+
+跟随末尾、暂停、级别过滤、空数据、禁用。
+
+## 事件
+
+Changed() 报告暂停或过滤变化。
+
+## 键盘操作
+
+Tab 聚焦暂停和级别；方向键切换级别；Space 激活暂停。
+
+## 限制
+
+追加或替换日志提交新切片；暂停冻结条数。

docs/components/448-trace-waterfall.md

@@ -0,0 +1,38 @@
+# 448 TraceWaterfall · 调用链瀑布图
+
+## 用途
+
+按跨度父子层级与耗时展示调用链，并读取跨度详情。
+
+## 最小示例
+
+```go
+spans := []mujica.TraceSpan{{ID: "root", Name: "GET /api", Service: "gateway", Duration: 200 * time.Millisecond}, {ID: "db", Parent: "root", Name: "Query", Service: "database", Start: 20 * time.Millisecond, Duration: 80 * time.Millisecond}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.TraceWaterfall(c, spans, mujica.TraceWaterfallOptions{}).Changed() {
+		fmt.Println("span selected")
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+Height 默认 320 DIP；TraceSpan.ID 唯一，Name 必填；Parent 关联父跨度；Start、Duration 为非负时间；Error 标记失败。
+
+## 状态
+
+空数据、跨度选择、失败跨度、父级禁用。
+
+## 事件
+
+Changed() 表示选择了跨度。
+
+## 键盘操作
+
+Tab 聚焦跨度；上下方向键移动；Enter 读取详情。
+
+## 限制
+
+更新调用链提交新切片；跨度父子关系须构成树。

docs/components/449-resource-gauge.md

@@ -0,0 +1,38 @@
+# 449 ResourceGauge · 资源仪表
+
+## 用途
+
+展示 CPU、内存与磁盘使用量和阈值状态。
+
+## 最小示例
+
+```go
+readings := []mujica.ResourceReading{{Name: "CPU", Used: 45, Total: 100}, {Name: "Memory", Used: 6.4, Total: 8, Unit: "GB"}, {Name: "Disk", Used: 470, Total: 500, Unit: "GB"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ResourceGauge(c, readings, mujica.ResourceGaugeOptions{}).Changed() {
+		fmt.Println("retry")
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+Warn 默认 0.7，Critical 默认 0.9，须 0 < Warn < Critical < 1；Height 默认 150 DIP；Status、Error 控制加载与失败；Name 必填，Total 为有限正数，Used 在 0 到 Total 内。
+
+## 状态
+
+正常、偏高、危险、空资源、加载、失败、父级禁用。
+
+## 事件
+
+Changed() 表示请求重试；调用方更新 readings。
+
+## 键盘操作
+
+Tab 聚焦仪表；方向键读取数值与阈值文字。
+
+## 限制
+
+资源采样与容量换算由调用方完成。

docs/components/450-system-monitor.md

@@ -0,0 +1,39 @@
+# 450 SystemMonitor · 系统监视器
+
+## 用途
+
+在同一时间轴上组合多资源折线，展示最新采样值。
+
+## 最小示例
+
+```go
+times := []time.Time{time.Date(2026, 10, 5, 9, 0, 0, 0, time.UTC), time.Date(2026, 10, 5, 9, 0, 5, 0, time.UTC)}
+metrics := []mujica.MonitorMetric{{Name: "CPU", Unit: "%", Samples: []float64{42, 51}}, {Name: "Memory", Unit: "GB", Samples: []float64{3.2, 3.4}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.SystemMonitor(c, times, metrics, mujica.SystemMonitorOptions{}).Changed() {
+		fmt.Println("retry")
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+Height 为单图高度，默认 110 DIP；Status、Error 控制加载与失败；每个 MonitorMetric.Name 必填，Samples 与 times 等长。
+
+## 状态
+
+实时采样、空资源、加载、失败、父级禁用。
+
+## 事件
+
+Changed() 表示请求重试。
+
+## 键盘操作
+
+Tab 到图例及图；方向键读取采样点；Home、End 到边界。
+
+## 限制
+
+采样由调用方提供；更新采样提交新切片；NaN 表示缺测。

docs/components/451-refresh-interval-selector.md

@@ -0,0 +1,42 @@
+# 451 RefreshIntervalSelector · 刷新间隔选择
+
+## 用途
+
+选择自动刷新间隔，报告手动与定时刷新请求。
+
+## 最小示例
+
+```go
+interval := 30 * time.Second
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.RefreshIntervalSelector(c, &interval, mujica.RefreshIntervalSelectorOptions{})
+	if r.Refresh {
+		fmt.Println("refresh")
+	}
+	if r.Changed {
+		fmt.Println("interval", interval)
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+Intervals 默认提供 5、10、30 秒、1、5 分钟；0 表示关闭；选项须为正整数秒；Refreshing 暂停计时，Disabled 禁用。
+
+## 状态
+
+关闭自动刷新、自动刷新、刷新中、禁用。
+
+## 事件
+
+Refresh 表示请求刷新；Changed 报告间隔变化。
+
+## 键盘操作
+
+Tab 到选择器与按钮；方向键选择间隔；Enter 激活。
+
+## 限制
+
+调用方收到 Refresh 后执行加载并设置 Refreshing。

docs/components/452-dashboard-filter-bar.md

@@ -0,0 +1,39 @@
+# 452 DashboardFilterBar · 仪表盘过滤栏
+
+## 用途
+
+编辑时间范围、环境和标签，并支持清除。
+
+## 最小示例
+
+```go
+var filters mujica.DashboardFilters
+opts := mujica.DashboardFilterBarOptions{Envs: []string{"production", "staging"}, Tags: []string{"api", "db"}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.DashboardFilterBar(c, &filters, opts).Changed() {
+		fmt.Println("filters changed")
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+Ranges 默认 15 分钟、1 小时、1 天、7 天；Env 与 Tags 来自选项；Range 为 0 使用调用方默认；Disabled 禁用。
+
+## 状态
+
+默认过滤、已选择、已清除、禁用。
+
+## 事件
+
+Changed() 报告过滤或清除。
+
+## 键盘操作
+
+Tab 遍历控件；方向键选择；Space 切换标签；Escape 关闭弹层。
+
+## 限制
+
+过滤请求由调用方执行；选中值须存在于提供的选项中。

docs/components/453-json-viewer.md

@@ -0,0 +1,40 @@
+# 453 JsonViewer · JSON 查看器
+
+## 用途
+
+显示 JSON 树、折叠节点、复制路径并搜索键和值。
+
+## 最小示例
+
+```go
+data := `{"server":{"port":8080},"ready":true}`
+var state mujica.JsonViewerState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.JsonViewer(c, data, &state, mujica.JsonViewerOptions{})
+	if r.Copied != "" {
+		fmt.Println("path copied")
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+state 必填；Height 默认 360 DIP；Expanded 首次展开所有节点；Query 为搜索文本，Current 为匹配索引。
+
+## 状态
+
+展开、折叠、搜索匹配、无匹配、解析失败、父级禁用。
+
+## 事件
+
+Copied 为写入剪贴板的路径。
+
+## 键盘操作
+
+Tab 到搜索、复制和树；上下移动；左右展开折叠；Enter 切换节点。
+
+## 限制
+
+JSONPath 使用点号、数组索引和带引号的键；解析结果按数据变化缓存。

docs/components/454-json-editor.md

@@ -0,0 +1,39 @@
+# 454 JsonEditor · JSON 编辑器
+
+## 用途
+
+编辑 JSON、格式化并显示解析错误行列与上下文。
+
+## 最小示例
+
+```go
+text := `{"port":8080,"ready":true}`
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.JsonEditor(c, &text, mujica.JsonEditorOptions{})
+	if r.Changed {
+		fmt.Println("valid", r.Valid)
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+Label 默认 JSON；MinHeight 默认 160，MaxHeight 默认 400 DIP；Disabled 禁用；text 必填。
+
+## 状态
+
+有效 JSON、解析失败、错误行列定位、禁用。
+
+## 事件
+
+Changed 报告文本变化；Valid 为解析结果；Line、Column 为从 1 开始的错误位置。
+
+## 键盘操作
+
+Tab 到格式化和文本框；标准文本编辑与剪贴板快捷键。
+
+## 限制
+
+编辑单个 JSON 值；格式化使用两个空格缩进。

docs/components/455-schema-tree.md

@@ -0,0 +1,40 @@
+# 455 SchemaTree · 数据库结构树
+
+## 用途
+
+显示数据库、表、视图、列和索引树。
+
+## 最小示例
+
+```go
+roots := []mujica.SchemaNode{{Name: "app", Children: []mujica.SchemaNode{{Name: "users", Kind: mujica.SchemaTable, Children: []mujica.SchemaNode{{Name: "id", Kind: mujica.SchemaColumn, Detail: "bigint"}, {Name: "users_pk", Kind: mujica.SchemaIndex, Detail: "(id)"}}}}}}
+var state mujica.SchemaTreeState
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.SchemaTree(c, &state, roots, mujica.SchemaTreeOptions{}).Changed() {
+		path, _ := state.Selected()
+		fmt.Println("selected", path)
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+state 必填；Height 默认 360 DIP；Name 必填，兄弟名称唯一；Kind 使用枚举，Detail 为类型说明。
+
+## 状态
+
+展开、折叠、选择、空结构、父级禁用。
+
+## 事件
+
+Changed() 报告选择变化；state.Selected() 返回路径。
+
+## 键盘操作
+
+Tab 进入树；上下选择；左右展开折叠。
+
+## 限制
+
+路径以斜线分隔；节点名称须保持路径唯一；更新结构提交新切片。

docs/components/456-api-request-builder.md

@@ -0,0 +1,42 @@
+# 456 ApiRequestBuilder · API 请求构建器
+
+## 用途
+
+编辑方法、URL、参数、请求头和正文，报告发送请求。
+
+## 最小示例
+
+```go
+request := mujica.ApiRequest{Method: "POST", URL: "https://example.com/api", Headers: []mujica.KeyValue{{Key: "Accept", Value: "application/json", Enabled: true}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.ApiRequestBuilder(c, &request, mujica.ApiRequestBuilderOptions{})
+	if r.Send {
+		fmt.Println("send", request.Method)
+	}
+	if r.Changed {
+		fmt.Println("request changed")
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+Sending 防止重复发送；Disabled 禁用；Method 默认为 GET；URL 须为 HTTP 或 HTTPS；启用且键非空的参数进入预览。
+
+## 状态
+
+空地址、有效地址、无效地址、发送中、禁用。
+
+## 事件
+
+Send 表示请求发送；Changed 为编辑变化。
+
+## 键盘操作
+
+Tab 遍历控件；URL 框 Enter 发送；左右切换标签页。
+
+## 限制
+
+网络请求由调用方执行；支持 GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS。

docs/components/457-response-viewer.md

@@ -0,0 +1,38 @@
+# 457 ResponseViewer · 响应查看器
+
+## 用途
+
+显示状态码、耗时、大小、JSON 或文本正文与响应头。
+
+## 最小示例
+
+```go
+response := &mujica.ApiResponse{Status: 200, Duration: 182 * time.Millisecond, Size: 32, Body: `{"ready":true}`, Headers: []mujica.KeyValue{{Key: "Content-Type", Value: "application/json"}}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.ResponseViewer(c, response, mujica.ResponseViewerOptions{}).Changed() {
+		fmt.Println("retry")
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+resp 为 nil 时显示等待；Status、Error 控制请求状态；Height 默认 320 DIP；HTTP 状态码须在 100 到 599；Size 为非负字节数。
+
+## 状态
+
+等待请求、加载、失败、JSON 正文、文本正文、空正文、空响应头、父级禁用。
+
+## 事件
+
+Changed() 表示重试。
+
+## 键盘操作
+
+Tab 到标签页；左右切换正文与响应头；JSON 树沿用查看器键盘操作。
+
+## 限制
+
+响应来自调用方；正文为有效 JSON 时使用树视图；其余正文使用文本。

docs/components/458-key-value-input.md

@@ -0,0 +1,38 @@
+# 458 KeyValueInput · 键值对输入
+
+## 用途
+
+编辑键值对、切换启用状态并增删行。
+
+## 最小示例
+
+```go
+rows := []mujica.KeyValue{{Key: "Accept", Value: "application/json", Enabled: true}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.KeyValueInput(c, &rows, mujica.KeyValueInputOptions{}).Changed() {
+		fmt.Println("rows", len(rows))
+	}
+}
+ui.Render(view, 720, 480, 1)
+```
+
+## 参数
+
+KeyPlaceholder、ValuePlaceholder 默认内置文案；Label 为控件名称；MaxHeight 默认 320 DIP；Disabled 禁用；rows 必填。
+
+## 状态
+
+空集合、启用行、停用行、禁用。
+
+## 事件
+
+Changed() 报告编辑、启用切换或增删。
+
+## 键盘操作
+
+Tab 到各字段及按钮；Space 切换启用；Enter 激活增删。
+
+## 限制
+
+行顺序保持输入顺序；大量行采用虚拟化。