Merge branch 'main' into worktree-agent-ac0c9e7144c57cf07

docs/components/001-app-shell.md

@@ -0,0 +1,53 @@
+# 001 AppShell 应用外壳
+
+## 用途
+
+搭建桌面窗口的整体骨架：顶部标题栏、左侧侧栏、主内容区和底部状态栏四个插槽。侧栏可折叠为只含切换按钮的窄条；侧栏与主内容各自独立滚动。
+
+## 最小示例
+
+```go
+var collapsed bool
+mujica.AppShell(c, &collapsed, mujica.AppShellOptions{
+	TitleBar: func() { mujica.TitleBar(c, "Court Records", mujica.TitleBarOptions{}) },
+	Sidebar:  func() { ui.Text(c, "Chronicles") },
+	Content:  func() { ui.Text(c, "The Grand Hall") },
+})
+```
+
+签名：`func AppShell(c *ui.Context, collapsed *bool, opts AppShellOptions) AppShellResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `collapsed` | `*bool` | 必填 | 侧栏是否折叠，由应用持有；为 nil 时 panic。 |
+| `TitleBar` | `func()` | nil | 顶部插槽，通常放 `TitleBar`。 |
+| `Sidebar` | `func()` | nil | 侧栏内容，自带独立滚动；为 nil 时没有侧栏与折叠快捷键。 |
+| `Content` | `func()` | 必填 | 主内容，自带独立滚动；为 nil 时 panic。 |
+| `StatusBar` | `func()` | nil | 底部插槽，通常放 `StatusBar`。 |
+| `SidebarWidth` | `float32` | 240 | 展开时侧栏宽度（DIP）；负数 panic。 |
+| `ContentScroll` | `*ui.ScrollState` | nil | 保存主内容滚动位置；nil 时按位置保留。 |
+
+返回 `AppShellResult`，内嵌 `*ui.Element`。
+
+## 状态
+
+- 展开：侧栏宽 `SidebarWidth`，顶部右侧为收起按钮。
+- 折叠：侧栏收为 `28 + 4 单位` 的窄条，只保留展开按钮。宽度变化 120 ms，减少动画时直接切换。
+- 切换按钮有悬停、按下和键盘焦点环；折叠不会重置主内容滚动位置。
+
+## 事件
+
+- `Toggled`：本帧侧栏被展开或折叠（按钮或快捷键），只触发一次。
+
+## 键盘操作
+
+- `Cmd+B`（macOS）/ `Ctrl+B`（其他平台）：切换侧栏。焦点控件先处理该键，富文本等若占用此键则不会触发。
+- Tab 依次到达切换按钮、侧栏与内容中的控件；滚动区域内容溢出时可获得焦点，方向键、Page Up/Down、Home、End 滚动。
+
+## 限制
+
+- 窄窗口不会自动折叠，由应用根据窗口宽度设置 `*collapsed`。
+- 折叠动画期间侧栏内容立即隐藏，只有宽度过渡。
+- 快捷键固定为 Cmd/Ctrl+B，不可配置。

docs/components/002-title-bar.md

@@ -0,0 +1,43 @@
+# 002 TitleBar 标题栏
+
+## 用途
+
+窗口顶部的标题行：衬线体应用标题、前后工具插槽。空白处可拖动窗口，并为系统窗口按钮留出空间。配合 `mygo.TitleBarHidden` 使用。
+
+## 最小示例
+
+```go
+mujica.TitleBar(c, "Court Records", mujica.TitleBarOptions{
+	Trailing: func() { mujica.Button(c, "Share", mujica.ButtonOptions{Variant: mujica.Ghost}) },
+})
+```
+
+签名：`func TitleBar(c *ui.Context, title string, opts TitleBarOptions) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `title` | `string` | 必填 | 标题文字，过长时单行省略。 |
+| `Leading` | `func()` | nil | 标题前的工具，如侧栏开关。 |
+| `Trailing` | `func()` | nil | 标题后的工具。 |
+
+## 状态
+
+- 高度取 `c.TitleBar().Height` 与 `控件高度 + 2 单位` 中较大者（默认密度 44 DIP）。
+- 左右内边距在 `c.TitleBar().Left/Right` 之外再加 3 单位，不覆盖系统按钮；全屏时预留为 0。
+- Surface 底色，底部 1 DIP Border 分隔线。
+
+## 事件
+
+TitleBar 本身无事件；插槽中控件照常报告 `Clicked` 等事件。
+
+## 键盘操作
+
+插槽控件照常接受 Tab、Enter、Space。标题栏本身不获取焦点。
+
+## 限制
+
+- 拖动、双击缩放由 MyGo `DragWindow` 实现，只作用于非交互区域；需真机验证，无窗口测试无法覆盖。
+- 系统窗口按钮外观由系统决定，不换肤。
+- 普通有标题栏的窗口中 `c.TitleBar()` 为零，组件只是一行普通标题。

docs/components/003-status-bar.md

@@ -0,0 +1,63 @@
+# 003 StatusBar 状态栏
+
+## 用途
+
+窗口底部的状态条，分左右两组条目：状态文字、图标、进度与可点击操作。宽度不足时自动隐藏次要条目，并显示剩余数量。
+
+## 最小示例
+
+```go
+bar := mujica.StatusBar(c, mujica.StatusBarOptions{
+	Left:  []mujica.StatusItem{{ID: "sync", Text: "Syncing", ShowProgress: true, Progress: 0.4}},
+	Right: []mujica.StatusItem{{ID: "bell", Label: "Notifications", Icon: icons.Must("bell"), Action: true}},
+})
+if bar.Clicked == "bell" {
+	opened++
+}
+```
+
+签名：`func StatusBar(c *ui.Context, opts StatusBarOptions) StatusBarResult`
+
+## 参数
+
+`StatusBarOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Left` | `[]StatusItem` | nil | 左侧条目，从左到右。 |
+| `Right` | `[]StatusItem` | nil | 右侧条目，从左到右。 |
+
+`StatusItem`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `ID` | `string` | 必填 | 稳定键，也是 `Clicked` 的值；为空或重复 panic。 |
+| `Text` | `string` | "" | 状态文字（12 DIP）。 |
+| `Icon` | `*ui.SVG` | nil | 前置图标（14 DIP）。 |
+| `Tone` | `StatusItemTone` | `StatusItemNeutral` | 语义色：Neutral、Success、Warning、Danger、Info。 |
+| `ShowProgress` | `bool` | false | 显示 64 DIP 进度条。 |
+| `Progress` | `float32` | 0 | 进度 0–1，超出 panic。 |
+| `Action` | `bool` | false | 条目成为按钮。 |
+| `Label` | `string` | "" | 无文字条目的无障碍名称；`Text` 与 `Label` 都为空时 panic。 |
+| `Secondary` | `bool` | false | 空间不足时优先隐藏。 |
+
+## 状态
+
+- 默认：Surface 底色，顶部 Border 线，组内条目以细线分隔。
+- 操作条目：悬停 SurfaceHover，按下 Selection，键盘焦点环。
+- 折叠：按“右组末项 → 左组首项”的顺序隐藏 `Secondary` 条目，直到放得下；显示 `+N`，悬停提示列出被隐藏条目，无障碍名称为“另有 N 项”。主要条目永不隐藏。
+- 进度：AccentText 填充，Border 轨道，描述为百分比。
+
+## 事件
+
+- `Clicked`：本帧被点击的操作条目 ID，没有则为空。一次点击只报告一次。
+
+## 键盘操作
+
+Tab 到达操作条目，Enter 或 Space 触发。纯文字条目不进入 Tab 序列。
+
+## 限制
+
+- 折叠依据上一帧的宽度和文字测量估算，窗口缩放后下一帧生效。
+- 被隐藏条目只在 `+N` 的提示中列出，提示仅悬停可见，键盘用户通过无障碍名称得知数量。
+- 不提供不确定进度动画；需要时在 `Text` 中说明。

docs/components/004-container.md

@@ -0,0 +1,45 @@
+# 004 Container 容器
+
+## 用途
+
+为一组内容提供内边距、最大宽度、水平居中、填充父级和裁剪，适合正文、设置页等需要可读行宽的区域。
+
+## 最小示例
+
+```go
+mujica.Container(c, mujica.ContainerOptions{MaxWidth: 320, Center: true}, func() {
+	ui.Text(c, "A centered column of prose.")
+})
+```
+
+签名：`func Container(c *ui.Context, opts ContainerOptions, children func()) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Padding` | `Space` | `SpaceL`（4 单位，默认密度 16 DIP） | 四周内边距，随密度缩放。 |
+| `MaxWidth` | `float32` | 0（不限） | 最大宽度 DIP；负数 panic。 |
+| `Center` | `bool` | false | 占满父级宽度后受 `MaxWidth` 限制并水平居中。 |
+| `Fill` | `bool` | false | 占满父级内容区（宽和高）。 |
+| `Clip` | `bool` | false | 裁剪超出的内容。 |
+| `children` | `func()` | 必填 | 子内容，纵向排列；nil 时 panic。 |
+
+`Space` 取值：`SpaceDefault`（组件默认）、`SpaceNone`、`SpaceXS`（1 单位）、`SpaceS`（2）、`SpaceM`（3）、`SpaceL`（4）、`SpaceXL`（6）、`SpaceXXL`（8）。单位为 Compact 3、Default 4、Comfortable 5 DIP。非法值 panic。
+
+## 状态
+
+布局组件，无交互状态。不绘制背景，可在返回的元素上调用 `Background`、`Border`。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点。
+
+## 限制
+
+- 只做水平居中；垂直居中请用 `Stack` 的对齐或 MyGo `Center()`。
+- 子内容固定纵向排列，需要横向时在内部放 `Stack`。

docs/components/005-stack.md

@@ -0,0 +1,49 @@
+# 005 Stack 堆叠
+
+## 用途
+
+按横向或纵向排列子元素，统一间距、对齐与换行。用 `StackItem` 包裹可隐藏的子项，隐藏时不占位置也不留间距。
+
+## 最小示例
+
+```go
+mujica.Stack(c, mujica.StackOptions{Horizontal: true, Gap: mujica.SpaceM}, func() {
+	mujica.Button(c, "Save", mujica.ButtonOptions{})
+	mujica.StackItem(!showDraft, func() { mujica.Button(c, "Draft", mujica.ButtonOptions{Variant: mujica.Secondary}) })
+	mujica.Button(c, "Cancel", mujica.ButtonOptions{Variant: mujica.Ghost})
+})
+```
+
+签名：
+
+- `func Stack(c *ui.Context, opts StackOptions, children func()) *ui.Element`
+- `func StackItem(hidden bool, build func())`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Horizontal` | `bool` | false | 横向排列；否则纵向。 |
+| `Gap` | `Space` | `SpaceS`（2 单位） | 子项间距，随密度缩放。 |
+| `Align` | `StackAlign` | `StackAlignAuto` | 交叉轴对齐：Auto（纵向拉伸、横向居中）、Start、Center、End、Stretch；非法值 panic。 |
+| `Justify` | `ui.Align` | `ui.Start` | 主轴分布：Start、Center、End、SpaceBetween、SpaceAround、SpaceEvenly。 |
+| `Wrap` | `bool` | false | 横向换行；纵向时设置会 panic。 |
+
+`StackItem`：`hidden` 为 true 时不构建 `build`，因此既不占空间也不产生间距。`build` 为 nil 时 panic。
+
+## 状态
+
+布局组件，无交互状态。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点；Tab 顺序即子项构建顺序。
+
+## 限制
+
+- 隐藏项不会被构建，其内部界面状态（如未提交的输入）随之丢弃；需要保留时把状态放在应用中。
+- 只有横向支持换行。

docs/components/006-grid.md

@@ -0,0 +1,57 @@
+# 006 Grid 网格
+
+## 用途
+
+按行列排布子元素：列宽可为固定尺寸、按内容或按比例分配剩余空间；子项可指定位置与跨行跨列。基于 MyGo 网格布局。
+
+## 最小示例
+
+```go
+mujica.Grid(c, mujica.GridOptions{Columns: []ui.Track{ui.Fixed(96), ui.Fr(1)}}, func() {
+	mujica.GridCell(c, mujica.GridCellOptions{ColumnSpan: -1}, func() { ui.Text(c, "Header") })
+	ui.Text(c, "Name")
+	ui.Text(c, "Ada")
+})
+```
+
+签名：
+
+- `func Grid(c *ui.Context, opts GridOptions, children func()) *ui.Element`
+- `func GridCell(c *ui.Context, opts GridCellOptions, build func()) *ui.Element`
+
+## 参数
+
+`GridOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Columns` | `[]ui.Track` | 一列 `Fr(1)` | 各列尺寸：`ui.Fixed(dip)`、`ui.Fr(n)`（分配剩余空间）、`ui.FitContent()`。 |
+| `Rows` | `[]ui.Track` | nil | 前几行尺寸；之后自动添加的行按内容高度。 |
+| `Gap` | `Space` | `SpaceM`（3 单位） | 列间距，也是默认行间距。 |
+| `RowGap` | `Space` | 同 `Gap` | 行间距。 |
+
+`GridCellOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Column`, `Row` | `int` | 0（自动放置） | 起始列、行，从 1 计；负数 panic。 |
+| `ColumnSpan`, `RowSpan` | `int` | 1 | 跨越轨道数；-1 跨到最后一条；小于 -1 panic。 |
+
+`GridCell` 内的单个子元素会拉伸铺满整个单元格，与网格直接子项一致。
+
+## 状态
+
+布局组件，无交互状态。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点；Tab 顺序为构建顺序。
+
+## 限制
+
+- 网格会构建全部子项；大量条目请使用虚拟化列表。
+- 不校验跨度是否超出列数，超出时由 MyGo 按其规则扩展。

docs/components/007-scroll-area.md

@@ -0,0 +1,49 @@
+# 007 ScrollArea 滚动区域
+
+## 用途
+
+纵向、横向或双向滚动内容。支持滚轮、触控板、滚动条拖动与键盘；可读取、设置并保留滚动位置。基于 MyGo `ui.Scroll`。
+
+## 最小示例
+
+```go
+var offset ui.ScrollState
+mujica.ScrollArea(c, &offset, mujica.ScrollAreaOptions{Label: "Log"}, func() {
+	for range 50 {
+		ui.Text(c, "A line of the log")
+	}
+}).Height(200)
+```
+
+签名：`func ScrollArea(c *ui.Context, state *ui.ScrollState, opts ScrollAreaOptions, children func()) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `state` | `*ui.ScrollState` | nil | 滚动位置。设置 `X`/`Y` 即滚动到该处，`math.MaxFloat32` 表示末尾；组件写回 `MaxX`/`MaxY`。nil 时按区域在视图中的位置保留。 |
+| `Direction` | `ScrollDirection` | `ScrollVertical` | `ScrollVertical`、`ScrollHorizontal`、`ScrollBoth`；非法值 panic。 |
+| `Label` | `string` | "" | 区域的无障碍名称。 |
+| `children` | `func()` | 必填 | 内容；nil 时 panic。 |
+
+需给区域尺寸（`Height`、`Grow` 等）。
+
+## 状态
+
+- 内容溢出时区域可获得焦点，键盘焦点环画在区域内侧（2 DIP，Focus 色），避免被父级裁剪。
+- 不溢出时不进入 Tab 序列。
+- 滚动条为 MyGo 叠加式滑块，颜色取主题 Scrollbar（TextMuted 50%），指针悬停时显示，不占布局空间。
+- 切换主题、折叠周围布局都不重置位置。
+
+## 事件
+
+无独立事件；比较 `state.X`/`state.Y` 的变化即可得知滚动。
+
+## 键盘操作
+
+焦点在区域或其内容上时：方向键滚动 40 DIP，Page Up/Down 与 Space/Shift+Space 翻页，Home/End 到顶部/底部（macOS 另有 Cmd+↑/↓）。文本输入等自行处理这些键的控件优先。
+
+## 限制
+
+- 滚动条只在悬停时显示，不提供常驻滚动条（MyGo 滚动条不占空间的设计）。
+- 大量行请使用虚拟化列表，ScrollArea 会构建全部子项。

docs/components/008-split-pane.md

@@ -0,0 +1,64 @@
+# 008 SplitPane 分栏
+
+## 用途
+
+将区域分为左右（或上下）两栏，中间分隔条可拖动、可用键盘调整；两栏有各自最小尺寸，可指定一栏可折叠。
+
+## 最小示例
+
+```go
+split := mujica.SplitPaneState{Size: 160}
+mujica.SplitPane(c, &split, mujica.SplitPaneOptions{MinFirst: 120, Collapsible: mujica.SplitPaneFirst},
+	func() { ui.Text(c, "Files") },
+	func() { ui.Text(c, "Editor") },
+).Fill()
+```
+
+签名：`func SplitPane(c *ui.Context, state *SplitPaneState, opts SplitPaneOptions, first, second func()) SplitPaneResult`
+
+## 参数
+
+`SplitPaneState`（应用持有，nil 时 panic）
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Size` | `float32` | 0（首次布局后取一半） | 第一栏宽度（纵向时为高度），DIP。每帧被限制在最小尺寸之间。 |
+| `Collapsed` | `bool` | false | 可折叠栏是否折叠；折叠时保留 `Size` 以便恢复。未设置 `Collapsible` 却为 true 时 panic。 |
+
+`SplitPaneOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Vertical` | `bool` | false | 第一栏在上。 |
+| `MinFirst`, `MinSecond` | `float32` | 10 单位（默认 40 DIP） | 两栏最小尺寸；负数 panic。 |
+| `Collapsible` | `SplitPaneSide` | `SplitPaneNeither` | 可折叠的栏：`SplitPaneFirst` 或 `SplitPaneSecond`。 |
+
+返回 `SplitPaneResult`，内嵌 `*ui.Element`。
+
+## 状态
+
+- 分隔条为 1 DIP ControlBorder 线，命中区域 1.5 单位宽；悬停或拖动时变为 AccentText；键盘焦点时在命中区域外画焦点环。
+- 折叠时该栏不构建，分隔条贴边并显示一段短标记，提示可从此处拉开。
+- 无障碍：角色为 splitter，名称“分隔条”，描述为第一栏所占百分比或“已折叠”。
+
+## 事件
+
+- `Resized`：本帧尺寸改变（拖动或键盘）。
+- `Toggled`：本帧折叠或展开。
+
+## 键盘操作
+
+Tab 聚焦分隔条后：
+
+- ←/→（纵向为 ↑/↓）：移动 4 单位，到达最小尺寸后停止。
+- 可折叠栏已在最小尺寸时继续朝它按方向键：折叠；折叠后按反方向键：展开。
+- Home / End：移到最小 / 最大位置。
+- Enter：切换可折叠栏（未设置 `Collapsible` 时不占用 Enter）。
+
+指针：拖动分隔条；拖到可折叠栏最小尺寸的一半以内即折叠，拖回超过一半即展开；双击切换折叠。
+
+## 限制
+
+- 未直接使用 MyGo `ui.Split`：它的最小栏宽固定为 10 个间距单位（`ui/split.go:20`），没有折叠能力，且分隔条元素不对外暴露，无法挂接 Enter、Home、End。本组件用 MyGo 公开的 `Focusable`、`Dragged`、`Shortcut`、`RoleSplitter` 重新组合，行为与 MyGo 分隔条一致并补齐上述功能。
+- MyGo 没有公开的无障碍数值范围接口，当前位置通过描述文字提供。
+- 键盘或拖动产生的尺寸在下一帧生效（组件会立即请求下一帧）。

docs/components/009-aspect-ratio.md

@@ -0,0 +1,41 @@
+# 009 AspectRatio 宽高比
+
+## 用途
+
+在父容器的宽高约束内放置一个保持指定宽高比的框，尽可能大并居中；子内容在框内居中，不被拉伸，超出部分裁剪。适合预览、视频占位、封面图。
+
+## 最小示例
+
+```go
+ui.Box(c).Size(320, 240).Children(func() {
+	mujica.AspectRatio(c, mujica.AspectRatioOptions{Ratio: 16.0 / 9}, func() {
+		ui.Text(c, "16 : 9")
+	})
+})
+```
+
+签名：`func AspectRatio(c *ui.Context, opts AspectRatioOptions, child func()) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Ratio` | `float32` | 1 | 宽 / 高；负数 panic。 |
+| `child` | `func()` | 必填 | 框内内容；nil 时 panic。需要铺满框时让子元素 `Fill()`。 |
+
+## 状态
+
+布局组件，无交互状态。返回的元素占满父级内容区，比例框位于其中央。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点。
+
+## 限制
+
+- 父级高度不确定（随内容增长）时只按宽度计算。
+- 框尺寸依据上一帧的父级尺寸计算，窗口缩放后组件请求下一帧完成调整（MyGo 布局的 `AspectRatio` 只能由宽推高，不能同时受宽高约束）。

docs/components/010-divider.md

@@ -0,0 +1,43 @@
+# 010 Divider 分隔线
+
+## 用途
+
+横向或纵向的细分隔线；横向可在中间放文字；可选旧金色单个菱形装饰。永不获取焦点，装饰不进入无障碍树。
+
+## 最小示例
+
+```go
+ui.Column(c).Padding(16).Gap(12).Children(func() {
+	mujica.Divider(c, mujica.DividerOptions{Ornament: true})
+	mujica.Divider(c, mujica.DividerOptions{Label: "Chapter II"})
+})
+```
+
+签名：`func Divider(c *ui.Context, opts DividerOptions) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Vertical` | `bool` | false | 纵向，放在横向行中，高度随行拉伸。 |
+| `Label` | `string` | "" | 横向分隔线中间的文字（衬线 12 DIP，TextMuted）。纵向带文字时 panic。 |
+| `Ornament` | `bool` | false | 线条改用 Ornament 色，并在中间画一个 7 DIP 菱形；有 `Label` 时文字取代菱形。 |
+
+## 状态
+
+- 默认：1 DIP Border 色细线。
+- 装饰：Ornament 色线与菱形。
+- 无悬停、焦点等交互状态。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点，Tab 直接跳过。
+
+## 限制
+
+- 方向不会根据父级自动判断，需要显式设置 `Vertical`。
+- 纵向不支持文字。

docs/components/011-text.md

@@ -0,0 +1,69 @@
+# 011 Text 文本
+
+## 用途
+
+正文文本：自动换行、按行数省略、可选择复制。`EditableText` 是 Text 的可编辑模式，就地修改一段短文本（如文件名），并展示调用方的保存进度与保存结果。
+
+## 最小示例
+
+```go
+name := "Coronation.md"
+saveErr := ""
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Text(c, "Order ID: 4821-AX", mujica.TextOptions{Selectable: true})
+	mujica.Text(c, "A long note that stops after two lines.", mujica.TextOptions{MaxLines: 2})
+	if mujica.EditableText(c, &name, mujica.EditableTextOptions{Error: saveErr}).Changed() {
+		saveErr = "" // save name here; set saveErr on failure
+	}
+}
+```
+
+## 参数
+
+`func Text(c *ui.Context, s string, opts TextOptions) *ui.Element`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `MaxLines` | `int` | `0` | 超过该行数时以省略号截断；`0` 不截断；`1` 为单行。负数 panic。 |
+| `Selectable` | `bool` | `false` | 允许用指针或键盘选择并复制文本。 |
+
+`func EditableText(c *ui.Context, value *string, opts EditableTextOptions) *ui.Element`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Saving` | `bool` | `false` | 调用方正在保存：显示加载标记，并禁止再次编辑。 |
+| `Error` | `string` | `""` | 调用方保存失败的说明，显示在文本下方并报告给辅助技术。 |
+| `Label` | `string` | `""` | 辅助技术读出的名称。 |
+
+## 状态
+
+- 默认：可编辑文本带虚线下边，提示可以编辑。
+- 悬停：背景变为 `SurfaceHover`，尺寸不变。
+- 聚焦：2 DIP 焦点环。
+- 编辑中：显示 MyGo 文本输入框，酒红边框，选中扩展名之前的部分。
+- 保存中（`Saving`）：显示加载标记，阻止进入编辑。
+- 错误（`Error`）：虚线变为 `Danger`，下方显示错误说明，保留已确认的值。
+
+## 事件
+
+- `EditableText(...).Changed()`：用户确认了一个新值，`*value` 已更新。调用方在此保存，并通过 `Saving` 与 `Error` 回传结果。
+- 取消编辑不产生事件，`*value` 不变。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 聚焦可编辑文本 |
+| Enter / 双击 | 开始编辑 |
+| Enter | 确认 |
+| Escape | 取消并恢复原值 |
+| 焦点移走 | 视为确认 |
+| Cmd/Ctrl+A、Cmd/Ctrl+C | 在 `Selectable` 文本上全选、复制 |
+
+## 限制
+
+- 编辑模式基于 `ui.EditableText`。MyGo 不报告“取消”事件，组件只能保证取消后值不变，不能通知调用方。
+- 编辑模式只支持单行文本。
+- 值为空字符串时文本区域没有可见文字；组件保留最小宽度和虚线，保证仍可点击。
+- MyGo 无法检测文本是否真的被截断，所以截断时不会自动显示完整内容的提示。

docs/components/012-heading.md

@@ -0,0 +1,43 @@
+# 012 Heading 标题
+
+## 用途
+
+页面与区块的三级衬线标题，可带副标题与旧金色装饰分隔线（对称细线加中央菱形）。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Heading(c, "The Grand Hall", mujica.HeadingOptions{Subtitle: "Winter ceremonies", Divider: true})
+	mujica.Heading(c, "Guest Ledger", mujica.HeadingOptions{Level: 2})
+}
+```
+
+## 参数
+
+`func Heading(c *ui.Context, title string, opts HeadingOptions) *ui.Element`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Level` | `int` | `0`（即 1） | 1、2、3 级，对应 28、22、18 DIP。其他值 panic。 |
+| `Subtitle` | `string` | `""` | 标题下方的说明文字，使用 `TextMuted`。 |
+| `Divider` | `bool` | `false` | 在下方绘制装饰分隔线，颜色为 `Ornament`。 |
+
+## 状态
+
+纯展示，仅默认状态。字号按系统文本缩放（`Preferences().TextScale`）放大。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点。装饰线不进入无障碍树。
+
+## 限制
+
+- 标题字体为 `theme.SerifFont`（Georgia、宋体类回退）；系统缺字时由系统回退字体显示。
+- MyGo v0.2.10 没有 Heading 角色（`ui/access.go` 的 Role 列表中没有），辅助技术把标题读作普通文本，无法按标题层级导航。
+- 分隔线只在 Heading 内绘制，不依赖 Divider 组件。

docs/components/013-icon.md

@@ -0,0 +1,47 @@
+# 013 Icon 图标
+
+## 用途
+
+按名称显示 `icons` 包内置的 Lucide SVG 图标，可设尺寸与语义颜色。名称不存在时显示可见的回退标记并写警告日志。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	ui.Row(c).Gap(8).Children(func() {
+		mujica.Icon(c, "star", mujica.IconOptions{})
+		mujica.Icon(c, "circle-check", mujica.IconOptions{Size: 20, Tone: mujica.IconSuccess, Label: "Done"})
+	})
+}
+```
+
+## 参数
+
+`func Icon(c *ui.Context, name string, opts IconOptions) *ui.Element`
+
+`name` 必填，空字符串 panic。可用名称见 `icons.Names()`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Size` | `float32` | `0`（即 16） | 宽高（DIP），建议 16、20、24。负数 panic。 |
+| `Tone` | `IconTone` | `IconInherit` | `IconInherit` 沿用文字颜色；另有 `IconMuted`、`IconAccent`、`IconSuccess`、`IconWarning`、`IconDanger`、`IconInfo`。未知值 panic。 |
+| `Label` | `string` | `""` | 有含义的图标的无障碍名称；为空时图标视为装饰，不进入无障碍树。 |
+
+## 状态
+
+- 默认：按语义颜色显示图标。
+- 加载失败（名称不存在）：在同尺寸方框中用 `Danger` 色绘制虚线框与斜线，提示文字为“缺少图标：名称”，无障碍名称相同。每个元素对每个缺失名称记录一次 `slog.Warn("mujica: icon missing", "name", ...)`。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点。
+
+## 限制
+
+- 只能使用 `icons` 包内置的图标。要显示任意 SVG，可直接用 `ui.Icon`。
+- 回退标记带悬停提示，但图标本身不获取焦点，键盘用户看不到这个提示，只能依赖无障碍名称。

docs/components/014-image.md

@@ -0,0 +1,60 @@
+# 014 Image 图片
+
+## 用途
+
+显示位图（`*ui.Bitmap`）或 SVG（`*ui.SVG`），可选包含或裁切填充；提供占位、加载中、加载失败三种状态和替代说明。
+
+## 最小示例
+
+```go
+var photo *ui.Bitmap // decode once with ui.DecodeBitmap, outside the view
+loading, loadErr := false, errors.New("timeout")
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	img := mujica.Image(c, photo, mujica.ImageOptions{
+		Width: 160, Height: 120, Crop: true, Alt: "Hall of mirrors",
+		Loading: loading, Err: loadErr,
+	})
+	if img.Retry {
+		loading, loadErr = true, nil // start loading again here
+	}
+}
+```
+
+## 参数
+
+`func Image(c *ui.Context, src ui.ImageSource, opts ImageOptions) ImageView`
+
+`src` 为 `nil`（未赋值的接口）时显示占位。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Width`, `Height` | `float32` | `0` | 盒子尺寸（DIP）。为 0 时图片使用自身尺寸；占位、加载、错误状态为 160×120。负数 panic。 |
+| `Crop` | `bool` | `false` | `true` 覆盖并裁切（`ui.Cover`）；`false` 完整放入（`ui.Contain`）。 |
+| `Alt` | `string` | `""` | 替代说明，供辅助技术读取；在其他状态下作为描述。 |
+| `Loading` | `bool` | `false` | 调用方正在加载。 |
+| `Err` | `error` | `nil` | 调用方加载失败；优先于 `Loading`。 |
+
+返回值 `ImageView`：`Element` 为外层元素；`Retry` 表示本帧点击了重试。
+
+## 状态
+
+优先级：错误 > 加载中 > 占位 > 图片。
+
+- 占位：浅色框内显示图片图标，名称“暂无图片”。
+- 加载中：框内显示 Spinner，名称“正在加载图片”。
+- 错误：显示错误图标、“图片加载失败”和“重试”按钮，`Err.Error()` 作为无障碍错误说明。
+
+## 事件
+
+- `ImageView.Retry`：用户点击了重试，或在按钮上按 Enter/Space。
+
+## 键盘操作
+
+只有错误状态的“重试”按钮可以聚焦（Tab），用 Enter 或 Space 触发。
+
+## 限制
+
+- 组件不读取文件，也不访问网络。解码（`ui.DecodeBitmap`、`ui.ParseSVG`）和异步加载由调用方完成，结果通过 `Window.Update` 回到界面线程，再设置 `Loading` 与 `Err`。
+- SVG 的绘制范围以 MyGo 支持的部分为准：不支持文本、嵌入图片、pattern、marker 和 filter。
+- 接口里装着 nil 指针（如 `(*ui.Bitmap)(nil)`）时不算 `nil`，不会显示占位。

docs/components/015-avatar.md

@@ -0,0 +1,47 @@
+# 015 Avatar 头像
+
+## 用途
+
+圆形人物头像。依次回退：图片 → 姓名首字母 → 默认人物图标。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	ui.Row(c).Gap(8).Children(func() {
+		mujica.Avatar(c, "Sakiko Togawa", mujica.AvatarOptions{Size: 40})
+		mujica.Avatar(c, "", mujica.AvatarOptions{})
+	})
+}
+```
+
+## 参数
+
+`func Avatar(c *ui.Context, name string, opts AvatarOptions) *ui.Element`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Image` | `*ui.Bitmap` | `nil` | 头像图片，按圆形裁切填充。 |
+| `Size` | `float32` | `0`（即 32） | 直径（DIP）。负数 panic。 |
+
+`name` 用作无障碍名称和首字母来源；为空时无障碍名称是“未命名”。
+
+## 状态
+
+- 图片：圆形裁切。
+- 首字母：取第一个和最后一个词的首字母（大写），衬线字体，`AccentText` 文字配 `Selection` 底色。
+- 无可用首字母：`SurfaceHover` 底色加人物图标。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点。辅助技术把头像读作以 `name` 命名的图片。
+
+## 限制
+
+- 中文姓名没有空格时按一个词处理，只取第一个字，例如“张伟”显示为“张”。
+- 头像不使用 MyGo `ui.Avatar`，因为它的尺寸固定为字号的 2.25 倍，无法配置（`ui/indicators.go:383`）。

docs/components/016-avatar-group.md

@@ -0,0 +1,54 @@
+# 016 AvatarGroup 头像组
+
+## 用途
+
+把多个头像重叠排列。超过最大数量时显示“+N”按钮，点开后在弹层中列出完整名单。
+
+## 最小示例
+
+```go
+people := []mujica.AvatarItem{
+	{Name: "Sakiko Togawa"}, {Name: "Uika Misumi"}, {Name: "Mutsumi Wakaba"},
+	{Name: "Umiri Yahata"}, {Name: "Nyamu Yutenji"},
+}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.AvatarGroup(c, people, mujica.AvatarGroupOptions{Max: 3})
+}
+```
+
+## 参数
+
+`func AvatarGroup(c *ui.Context, items []AvatarItem, opts AvatarGroupOptions) AvatarGroupView`
+
+`AvatarItem`：`Name string`、`Image *ui.Bitmap`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Max` | `int` | `0`（即 4） | 最多直接显示的头像数。负数 panic。 |
+| `Size` | `float32` | `0`（即 32） | 每个头像的直径。负数 panic。 |
+
+返回值 `AvatarGroupView`：`Element`；`Open` 表示完整名单正在显示；`Toggled` 表示本帧打开或关闭了名单。
+
+## 状态
+
+- 默认：头像之间重叠四分之一直径，用 2 DIP 窗口背景色描边分隔。
+- “+N”按钮：悬停、按下改变背景；聚焦时显示 2 DIP 焦点环。
+- 展开：按钮下方弹出 6 DIP 圆角面板，列出全部头像与姓名，超过 240 DIP 时滚动；遵循减少动画设置。
+
+## 事件
+
+- `AvatarGroupView.Toggled` / `Open`：名单展开或关闭（点击按钮、Enter、Space、Escape、点击外部）。同时记录 `slog.Debug("mujica: avatargroup toggle")`。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 聚焦“+N”按钮（读作“显示全部 N 人”） |
+| Enter / Space | 展开或收起完整名单 |
+| Escape | 关闭名单 |
+
+## 限制
+
+- 分隔描边使用窗口 `Background` 颜色，放在 `Surface` 卡片上时描边颜色会与卡片背景不同。
+- 名单中的条目只用于展示，不可选择。

docs/components/017-badge.md

@@ -0,0 +1,50 @@
+# 017 Badge 徽标
+
+## 用途
+
+显示短文字或计数。计数超过上限时显示为“上限+”。徽标可以内联排列，也可以钉在内容的某个角上。辅助技术朗读完整数值。
+
+## 最小示例
+
+```go
+unread := 120
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Badge(c, mujica.BadgeOptions{Text: "New", Tone: mujica.BadgeNeutral}, nil)
+	mujica.Badge(c, mujica.BadgeOptions{Count: unread, Label: "Unread", Position: mujica.BadgeTopRight}, func() {
+		mujica.Avatar(c, "Sakiko Togawa", mujica.AvatarOptions{})
+	})
+}
+```
+
+## 参数
+
+`func Badge(c *ui.Context, opts BadgeOptions, content func()) *ui.Element`
+
+`Position` 为 `BadgeInline` 时 `content` 必须为 `nil`；为角落位置时 `content` 必须不为 `nil`。否则 panic。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Text` | `string` | `""` | 显示的文字；非空时忽略 `Count`。 |
+| `Count` | `int` | `0` | 计数。`Text` 为空且计数为 0 时不显示徽标。负数 panic。 |
+| `Max` | `int` | `0`（即 99） | 显示上限，超过时显示 `Max+`。负数 panic。 |
+| `Tone` | `BadgeTone` | `BadgeAccent` | `BadgeAccent`、`BadgeNeutral`、`BadgeSuccess`、`BadgeWarning`、`BadgeDanger`、`BadgeInfo`。 |
+| `Position` | `BadgePosition` | `BadgeInline` | `BadgeTopRight`、`BadgeTopLeft`、`BadgeBottomRight`、`BadgeBottomLeft`：徽标中心对准内容的对应角。 |
+| `Label` | `string` | `""` | 计数的含义，朗读时放在完整数值前，如“Unread 1204”。 |
+
+## 状态
+
+纯展示。强调和危险色调使用实色填充（`OnAccent` 配 `Accent`，`OnDanger` 配 `DangerFill`）；成功、警告、信息色调只把语义色用在文字和边框上。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点。徽标的无障碍名称为 `Label` 加完整数值。
+
+## 限制
+
+- 角落徽标的位置相对于 `content` 所在的盒子。内容本身有外边距时，徽标不会跟着偏移。
+- 徽标使用 `RoleStatus`，部分屏幕阅读器可能在数值变化时主动播报。

docs/components/018-tag.md

@@ -0,0 +1,63 @@
+# 018 Tag 标签
+
+## 用途
+
+短标签，可带图标。可以点击，也可以关闭，点击标签和关闭标签是两个独立的操作，各有自己的焦点停靠点。
+
+## 最小示例
+
+```go
+tags := []string{"Baroque", "Gothic"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	ui.Row(c).Gap(8).Children(func() {
+		for i, t := range tags {
+			v := mujica.Tag(c, t, mujica.TagOptions{Icon: "star", Clickable: true, Closable: true})
+			v.Element.Key(t)
+			if v.Closed {
+				tags = append(tags[:i:i], tags[i+1:]...)
+			}
+		}
+	})
+}
+```
+
+## 参数
+
+`func Tag(c *ui.Context, label string, opts TagOptions) TagView`
+
+`label` 必填，空字符串 panic。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Icon` | `string` | `""` | 图标名称，见 Icon 组件。 |
+| `Clickable` | `bool` | `false` | 标签文字部分作为按钮，可以聚焦和点击。 |
+| `Closable` | `bool` | `false` | 显示 28×28 DIP 的关闭按钮。 |
+| `Disabled` | `bool` | `false` | 禁用点击和关闭，并移出 Tab 顺序。 |
+
+返回值 `TagView`：`Element`；`Clicked` 表示标签被激活；`Closed` 表示请求关闭。
+
+## 状态
+
+- 默认：`Surface` 底色、细边框、2 DIP 圆角。
+- 悬停 / 按下：可点击部分和关闭按钮分别变为 `SurfaceHover` / `Selection`。
+- 聚焦：对应部分显示 2 DIP 焦点环。
+- 禁用：由 MyGo 统一调暗，不响应输入。
+
+## 事件
+
+- `TagView.Clicked`：点击标签文字，或在聚焦时按 Enter/Space。点击关闭按钮不会触发它。
+- `TagView.Closed`：点击关闭按钮，或在关闭按钮上按 Enter/Space，或在聚焦的可点击标签上按 Delete/Backspace。组件不会自行移除标签，由调用方删除数据。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 先聚焦标签文字（仅 `Clickable`），再聚焦关闭按钮 |
+| Enter / Space | 激活当前聚焦的部分 |
+| Delete / Backspace | 在可点击标签上请求关闭（仅 `Closable`） |
+
+## 限制
+
+- 不可点击的标签不获取焦点，只能通过关闭按钮操作。
+- 标签不提供“选中”状态；需要可选标签时请使用 Toggle 类组件。

docs/components/019-link.md

@@ -0,0 +1,53 @@
+# 019 Link 链接
+
+## 用途
+
+带下划线的链接文本：打开外部地址、在 MyGo Router 中跳转路径，或作为应用内动作。可以显示打开失败的反馈。
+
+## 最小示例
+
+```go
+details := false
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Link(c, "Read the charter", mujica.LinkOptions{URL: "https://example.com/charter"})
+	if mujica.Link(c, "Show details", mujica.LinkOptions{}).Clicked() {
+		details = !details
+	}
+}
+```
+
+## 参数
+
+`func Link(c *ui.Context, label string, opts LinkOptions) *ui.Element`
+
+`label` 必填，空字符串 panic。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `URL` | `string` | `""` | 有协议的地址用系统默认应用打开。没有协议的路径（如 `/notes/42`、`?tab=info`）在 MyGo Router 中跳转。为空时是应用内动作。 |
+| `Error` | `string` | `""` | 调用方提供的打开失败说明，显示在链接下方，也报告给辅助技术。 |
+
+## 状态
+
+- 默认：`AccentText` 颜色，始终带 1 DIP 下划线。外部地址后面带“外部链接”小图标。
+- 悬停 / 按下：文字与下划线变为 `Text` 颜色，布局不变。
+- 聚焦：2 DIP 焦点环。
+- 错误：格式不正确的地址（无法解析，或 http/https 缺少主机名）不会打开，下方显示“无法打开此链接：地址”；`Error` 非空时优先显示 `Error`。
+
+## 事件
+
+- `Clicked()`：每次点击或按 Enter 都会报告，无论是否打开了地址。同时记录 `slog.Debug("mujica: link activate")`。
+
+## 键盘操作
+
+| 按键 | 作用 |
+| --- | --- |
+| Tab | 聚焦链接 |
+| Enter | 激活 |
+
+## 限制
+
+- MyGo v0.2.10 不报告打开失败。`ui.Link` 和 `Context.OpenURL` 不返回结果（`ui/context.go:270`、`ui/window.go:583`）。窗口宿主在 goroutine 中调用 `Shell.OpenExternal` 并丢弃它的错误（`content.go:55`）。因此组件只能自行检查地址格式，系统打开失败无法自动显示。需要这种反馈时，传空 `URL`，在 `Clicked()` 后由调用方在 goroutine 中调用 `mygo.Shell.OpenExternal(url)`。它会返回 error，把结果通过 `Window.Update` 写回 `Error`。
+- 路径是否交给 Router 由 MyGo 决定。没有 Router 时，路径会被当作 URL 交给系统打开。
+- 链接不能嵌入 `ui.RichText` 句子中作为行内元素，因为外部图标和错误说明需要额外的行布局。行内链接请直接使用 `ui.Link`。

docs/components/020-kbd.md

@@ -0,0 +1,55 @@
+# 020 Kbd 快捷键
+
+## 用途
+
+把单键或组合键显示为键帽。按平台显示：macOS 用 ⌘ ⇧ ⌥ ⌃ 等符号且不加连接符；其他平台显示 Ctrl、Shift、Alt，键之间用“+”连接。只做展示，不注册快捷键。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	ui.Row(c).Gap(6).Children(func() {
+		mujica.Text(c, "Command palette", mujica.TextOptions{})
+		mujica.Kbd(c, "Mod", "Shift", "P")
+	})
+}
+```
+
+## 参数
+
+`func Kbd(c *ui.Context, keys ...string) *ui.Element`
+
+至少要传一个键，键名不能为空，否则 panic。键名不区分大小写：
+
+| 键名 | macOS | 其他平台 |
+| --- | --- | --- |
+| `Mod` | ⌘（Command） | Ctrl |
+| `Ctrl` | ⌃ | Ctrl |
+| `Alt` | ⌥（Option） | Alt |
+| `Shift` | ⇧ | Shift |
+| `Enter` | ↩ | Enter |
+| `Esc` | esc | Esc |
+| `Tab` | ⇥ | Tab |
+| `Backspace` | ⌫ | Backspace |
+| `Delete` | ⌦ | Delete |
+| `Up` `Down` `Left` `Right` | ↑ ↓ ← → | ↑ ↓ ← → |
+
+其他键名按原样显示；单个字符转为大写。
+
+## 状态
+
+纯展示。键帽使用等宽字体、`Surface` 底色、`ControlBorder` 边框，底边 2 DIP。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不获取焦点，也不注册任何快捷键。辅助技术读出完整的组合键文字，例如“Command+Shift+P”或“Ctrl+Shift+P”。
+
+## 限制
+
+- 平台在编译时由 `runtime.GOOS` 决定。Gallery 的网页镜像显示的是运行 Go 进程那台机器的平台。
+- `Mod` 与 MyGo 的 `ui.Cmd` 一致：macOS 上是 Command，其他平台是 Control。

docs/components/021-button.md

@@ -0,0 +1,43 @@
+# 021 Button 按钮
+
+## 用途
+
+触发一个操作。提供主按钮、次按钮、描边、无底色和危险五种变体，可带图标，可显示加载与禁用。基于 MyGo `ui.ButtonBase`。
+
+## 最小示例
+
+```go
+if mujica.Button(c, "Save", mujica.ButtonOptions{Icon: icons.Must("check")}).Clicked() {
+	fmt.Println("saved")
+}
+```
+
+签名：`func Button(c *ui.Context, label string, opts ButtonOptions) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `label` | `string` | 必填（仅图标时可为空） | 按钮文字。 |
+| `Variant` | `ButtonVariant` | `Primary` | `Primary`、`Secondary`、`Outline`、`Ghost`、`Danger`。 |
+| `Icon` | `*ui.SVG` | `nil` | 文字前的 16 DIP 图标。 |
+| `Loading` | `bool` | `false` | 以菱形加载标记替换图标，保留尺寸与文字，阻止点击。 |
+| `Disabled` | `bool` | `false` | 不可点击、不进入 Tab 序列。 |
+| `Label` | `string` | `""` | 无文字按钮的无障碍名称。 |
+
+## 状态
+
+默认、悬停（底色加深或出现浅底）、按下、键盘聚焦（2 DIP 酒红焦点环，外留 2 DIP）、加载、禁用（MyGo 统一减淡）。高度不低于当前密度的控件高度（28/36/44 DIP）。
+
+## 事件
+
+`Clicked()`：鼠标在按钮内释放、Enter 或 Space 时为真，一次操作只报告一次。加载与禁用时始终为假。
+
+## 键盘操作
+
+Tab / Shift+Tab 聚焦；Enter 或 Space 触发。
+
+## 限制
+
+- 加载标记在减少动画模式下静止显示。
+- 危险变体的悬停与按下色由 `DangerFill` 混合黑色得到，未单独定义变量。

docs/components/022-icon-button.md

@@ -0,0 +1,42 @@
+# 022 IconButton 图标按钮
+
+## 用途
+
+只显示图标的方形按钮，用于工具栏与紧凑操作。操作名称必填，供辅助技术朗读，并作为默认提示文字。建立在 Button 之上。
+
+## 最小示例
+
+```go
+if mujica.IconButton(c, icons.Must("settings"), "Settings", mujica.IconButtonOptions{Variant: mujica.Ghost}).Clicked() {
+	fmt.Println("open settings")
+}
+```
+
+签名：`func IconButton(c *ui.Context, icon *ui.SVG, label string, opts IconButtonOptions) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `icon` | `*ui.SVG` | 必填 | 图标；为 nil 时 panic。 |
+| `label` | `string` | 必填 | 操作名称；为空时 panic。 |
+| `Variant` | `ButtonVariant` | `Primary` | 与 Button 相同的五种变体；工具栏通常用 `Ghost`。 |
+| `Tooltip` | `string` | 操作名称 | 悬停约 600 毫秒后显示的提示。 |
+| `Loading` | `bool` | `false` | 显示加载标记并阻止点击。 |
+| `Disabled` | `bool` | `false` | 禁用。 |
+
+## 状态
+
+同 Button：悬停、按下、聚焦、加载、禁用。边长等于当前密度的控件高度，不小于 28 DIP。
+
+## 事件
+
+`Clicked()`，一次操作一次。
+
+## 键盘操作
+
+Tab 聚焦；Enter 或 Space 触发。
+
+## 限制
+
+- 禁用时不显示提示：MyGo 的 `Hovered` 对禁用元素返回 false，提示随之不出现；名称仍作为无障碍描述保留。

docs/components/023-button-group.md

@@ -0,0 +1,53 @@
+# 023 ButtonGroup 按钮组
+
+## 用途
+
+把若干按钮拼成一条，共用边框与尺寸，只有外侧圆角。整个组是一个 Tab 停靠点，组内用方向键移动。基于 `ui.ButtonBase` 与 MyGo 焦点组 `FocusGroup`。
+
+## 最小示例
+
+```go
+items := []mujica.ButtonGroupItem{{Label: "Day"}, {Label: "Week"}, {Label: "Month"}}
+if i := mujica.ButtonGroup(c, items, mujica.ButtonGroupOptions{Label: "Range"}).ClickedItem(); i >= 0 {
+	fmt.Println("chose", items[i].Label)
+}
+```
+
+签名：`func ButtonGroup(c *ui.Context, items []ButtonGroupItem, opts ButtonGroupOptions) ButtonGroupResult`
+
+## 参数
+
+`ButtonGroupItem`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Label` | `string` | `""` | 文字；与 `Icon` 至少给一个，否则 panic。 |
+| `Icon` | `*ui.SVG` | `nil` | 图标。 |
+| `Name` | `string` | `""` | 仅图标项的无障碍名称。 |
+| `Disabled` | `bool` | `false` | 单项禁用；方向键跳过该项。 |
+
+`ButtonGroupOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Vertical` | `bool` | `false` | 纵向排列，使用上下方向键。 |
+| `Label` | `string` | `""` | 组的无障碍名称（工具栏角色）。 |
+| `Disabled` | `bool` | `false` | 禁用整组。 |
+
+`items` 为空时 panic。
+
+## 状态
+
+每项有悬停、按下、聚焦、禁用；相邻项共用一条 1 DIP 分隔边。
+
+## 事件
+
+`ClickedItem()` 返回本帧被点击项的下标，无点击时为 -1。
+
+## 键盘操作
+
+Tab 进入组（回到上次聚焦项）；横向组 Left/Right、纵向组 Up/Down 移动并循环；Home、End 到首末项；Enter 或 Space 触发。
+
+## 限制
+
+- 组内没有选中概念；需要保持选中请使用 ToggleGroup（033）。

docs/components/024-text-input.md

@@ -0,0 +1,49 @@
+# 024 TextInput 文本输入框
+
+## 用途
+
+单行文本编辑。支持占位、前后插槽、清空、只读与错误。编辑核心是 MyGo `ui.TextInputBase`，因此保留选择、撤销重做、剪贴板、右键菜单与输入法组合。
+
+## 最小示例
+
+```go
+r := mujica.TextInput(c, &name, mujica.TextInputOptions{Label: "Name", Placeholder: "Your name", Clearable: true})
+if r.Submitted() {
+	fmt.Println("hello", name)
+}
+```
+
+签名：`func TextInput(c *ui.Context, value *string, opts TextInputOptions) InputResult`
+
+`InputResult` 内嵌外层 `*ui.Element`，`Input` 字段是内部编辑元素，`Changed()`、`Submitted()` 报告事件。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `value` | `*string` | 必填 | 编辑的字符串；nil 时 panic。 |
+| `Placeholder` | `string` | `""` | 空值时的占位文字（TextMuted 色）。 |
+| `Label` | `string` | `""` | 无障碍名称，也供测试查找。 |
+| `Leading` / `Trailing` | `func()` | `nil` | 在框内左侧、右侧构建内容，如图标或单位。 |
+| `Clearable` | `bool` | `false` | 有内容时显示清空按钮；Escape 也会清空。 |
+| `Disabled` | `bool` | `false` | 禁用，不可聚焦。 |
+| `ReadOnly` | `bool` | `false` | 可聚焦、选择、复制，不可修改。 |
+| `Error` | `string` | `""` | 非空时边框变为 Danger，并在下方显示该文字；辅助技术同时朗读。 |
+
+## 状态
+
+默认（Surface 底、ControlBorder 边）、悬停（边框加深）、聚焦（边框 Focus 色；键盘聚焦另加焦点环）、只读（Background 底、Border 边）、错误、禁用。颜色变化 120 毫秒过渡，减少动画时直接切换。
+
+## 事件
+
+- `Changed()`：输入、粘贴、撤销或清空改变了值。只读时不会报告。
+- `Submitted()`：在框内按 Enter。
+
+## 键盘操作
+
+Tab 聚焦（全选内容）；Enter 提交；Escape 清空（仅 `Clearable` 且有内容时，否则交给外层）；Cmd/Ctrl+Z、Shift+Cmd+Z 撤销重做；Cmd/Ctrl+A/C/X/V；输入法组合期间不提交。
+
+## 限制
+
+- MyGo 没有公开的只读输入接口（只读模式仅用于 `Text.Selectable`，`editor.go:77`）。`ReadOnly` 通过让编辑器编辑一个副本并在同帧还原实现，撤销栈里可能出现被还原的步骤。
+- 清空按钮不进入 Tab 序列（与 MyGo SearchField 相同），键盘用 Escape 清空。

docs/components/025-text-area.md

@@ -0,0 +1,49 @@
+# 025 TextArea 多行文本框
+
+## 用途
+
+多行文本编辑，可设最小与最大高度，超出最大高度后在框内滚动；可显示字数；提交快捷键可配置。编辑核心是 MyGo `ui.TextAreaBase`，只排版可见段落，适合长文本。
+
+## 最小示例
+
+```go
+r := mujica.TextArea(c, &notes, mujica.TextAreaOptions{Label: "Notes", MaxHeight: 160, MaxLength: 200})
+if r.Submitted() {
+	fmt.Println("send", notes)
+}
+```
+
+签名：`func TextArea(c *ui.Context, value *string, opts TextAreaOptions) InputResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `value` | `*string` | 必填 | 编辑的字符串。 |
+| `Placeholder` | `string` | `""` | 占位文字。 |
+| `Label` | `string` | `""` | 无障碍名称。 |
+| `MinHeight` | `float32` | `0`（三行） | 编辑区最小高度，DIP。 |
+| `MaxHeight` | `float32` | `0`（随内容增长） | 编辑区最大高度，超出后滚动；小于 `MinHeight` 时 panic。 |
+| `MaxLength` | `int` | `0`（不显示） | 显示“当前 / 上限”字数（按 Unicode 字符计）；超出时变红并提示超出数量。 |
+| `SubmitKey` / `SubmitMods` | `ui.Key` / `ui.Modifiers` | Cmd+Enter（非 macOS 为 Ctrl+Enter） | 提交快捷键；`SubmitKey` 为零时使用默认值。 |
+| `Disabled` | `bool` | `false` | 禁用。 |
+| `ReadOnly` | `bool` | `false` | 只读，可选择复制。 |
+| `Error` | `string` | `""` | 错误文字；为空且超出 `MaxLength` 时自动显示超出提示。 |
+
+## 状态
+
+默认、悬停、聚焦、只读、错误、禁用，表现同 TextInput。
+
+## 事件
+
+`Changed()`：内容被用户改变。`Submitted()`：按下提交快捷键。
+
+## 键盘操作
+
+Enter 与 Shift+Enter 换行；提交快捷键提交；方向键、PageUp/PageDown 移动光标并滚动；撤销、剪贴板与输入法同 TextInput。
+
+## 限制
+
+- `MaxLength` 只提示，不截断输入，以免打断输入法组合与粘贴。
+- 提交快捷键不能是不带修饰键的 Enter：MyGo 编辑器先接收 Enter 并插入换行（`editor.go:161`）。
+- 只读实现方式同 TextInput。

docs/components/026-number-input.md

@@ -0,0 +1,49 @@
+# 026 NumberInput 数字输入框
+
+## 用途
+
+输入与步进数值，支持范围、步长、精度与空值。合并 MyGo 的 Number input（输入模式）与 Stepper（`StepperOnly` 仅步进模式）。
+
+## 最小示例
+
+```go
+if mujica.NumberInput(c, &copies, mujica.NumberInputOptions{Min: 1, Max: 99, Label: "Copies"}).Changed() {
+	fmt.Println("copies", copies)
+}
+```
+
+签名：`func NumberInput(c *ui.Context, value *float64, opts NumberInputOptions) InputResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `value` | `*float64` | 必填 | 数值；空值用 `math.NaN()` 表示，仅在 `AllowEmpty` 时允许。 |
+| `Min` / `Max` | `float64` | 都为 0 | 范围；相等（含零值）表示不限范围；`Min > Max` 时 panic。 |
+| `Step` | `float64` | `1` | 方向键与按钮的步长；负数 panic。 |
+| `Precision` | `int` | 取 `Step` 的小数位 | 保留与显示的小数位。 |
+| `AllowEmpty` | `bool` | `false` | 允许清空，值变为 NaN；从空值步进时从 0（夹在范围内）开始。 |
+| `StepperOnly` | `bool` | `false` | 只显示数值与上下箭头，不可输入；必须给出 `Min < Max`，且不能与 `AllowEmpty` 同用。 |
+| `Placeholder` | `string` | `""` | 空值时的占位。 |
+| `Label` | `string` | `""` | 无障碍名称。 |
+| `Disabled` | `bool` | `false` | 禁用。 |
+| `Error` | `string` | `""` | 调用方给出的错误。 |
+
+## 状态
+
+输入模式同 TextInput；输入非数字或超出范围时显示内置错误（“请输入数字”“请输入 a 到 b 之间的数字”），值保持上一次有效值；失去焦点后文本恢复为当前值并清除该错误。到达边界时对应按钮禁用。
+
+## 事件
+
+`Changed()`：值因输入、方向键、按钮或步进器改变。
+
+## 键盘操作
+
+输入模式：Up/Down 按步长增减。仅步进模式：Up/Right 增加、Down/Left 减少、Home 到最小、End 到最大；按住箭头持续步进。
+
+## 限制
+
+- 输入模式下的加减按钮不进入 Tab 序列，键盘用 Up/Down。
+- 仅步进模式复用 MyGo `ui.Stepper`，箭头高度来自主题间距，不随密度的控件高度变化。
+- MyGo `ui.Stepper` 的箭头不检查禁用（`indicators.go:216`），禁用时组件向它传入副本，保证值不被修改。
+- MyGo 的步进器吸附依赖有限边界（`widgets.go` 中 `snap`），所以仅步进模式要求有界。

docs/components/027-password-input.md

@@ -0,0 +1,42 @@
+# 027 PasswordInput 密码输入框
+
+## 用途
+
+遮蔽显示的密码输入，带显示/隐藏切换。允许粘贴；遮蔽时不允许复制与剪切。基于 `ui.TextInputBase(...).Password()`，辅助技术读不到遮蔽中的值。组件从不记录密码内容。
+
+## 最小示例
+
+```go
+if mujica.PasswordInput(c, &password, mujica.PasswordInputOptions{Label: "Password"}).Submitted() {
+	fmt.Println("signing in")
+}
+```
+
+签名：`func PasswordInput(c *ui.Context, value *string, opts PasswordInputOptions) InputResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `value` | `*string` | 必填 | 密码。 |
+| `Placeholder` | `string` | `""` | 占位文字。 |
+| `Label` | `string` | `""` | 无障碍名称。 |
+| `Disabled` | `bool` | `false` | 禁用（切换按钮同时禁用）。 |
+| `Error` | `string` | `""` | 错误文字。 |
+
+## 状态
+
+默认、悬停、聚焦、错误、禁用；遮蔽 / 显示两种模式，切换按钮的图标与名称（“显示密码”“隐藏密码”）随之变化。
+
+## 事件
+
+`Changed()`：内容改变。`Submitted()`：Enter。日志只写切换事件（`mujica: password_input reveal`，含是否显示），不写内容。
+
+## 键盘操作
+
+Tab 依次到输入框、切换按钮；切换按钮上 Space 或 Enter 切换；输入框中 Enter 提交，Cmd/Ctrl+V 粘贴。
+
+## 限制
+
+- MyGo 的 `Password()` 一旦设置无法撤销（`editor.go:791`），因此遮蔽与显示两种模式各用一个编辑器，切换时撤销历史和光标位置不保留，焦点留在切换按钮上。
+- 显示模式下内容是普通文本，可复制，辅助技术可朗读——这是用户主动选择的结果。

docs/components/028-search-input.md

@@ -0,0 +1,51 @@
+# 028 SearchInput 搜索框
+
+## 用途
+
+搜索模式：放大镜、输入、清空与提交。查找栏模式（`Find`）：在此基础上显示匹配数量、上一项与下一项，对应 MyGo 的 Search field 与 Find bar。匹配由调用方计算。
+
+## 最小示例
+
+```go
+matches := 0
+if query != "" {
+	matches = strings.Count(text, query)
+}
+r := mujica.SearchInput(c, &query, mujica.SearchInputOptions{Find: true, Matches: matches, Current: &current})
+if r.Moved() {
+	fmt.Println("show match", current)
+}
+```
+
+签名：`func SearchInput(c *ui.Context, query *string, opts SearchInputOptions) SearchInputResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `query` | `*string` | 必填 | 查询文字。 |
+| `Placeholder` | `string` | “搜索”或“查找” | 占位文字。 |
+| `Label` | `string` | 占位文字 | 无障碍名称。 |
+| `Disabled` | `bool` | `false` | 禁用（查找快捷键也停用）。 |
+| `Find` | `bool` | `false` | 开启查找栏模式。 |
+| `Matches` | `int` | `0` | 匹配数量；负数 panic。 |
+| `Current` | `*int` | `nil` | 当前匹配下标；`Find` 时必填，组件会把它夹在有效范围内。 |
+
+## 状态
+
+同 TextInput；查找栏模式下显示“第 n 项，共 m 项”或“无匹配”（状态角色，变化时可被朗读），无匹配时上一项/下一项禁用。
+
+## 事件
+
+- `Changed()`：查询改变（含清空）。
+- `Submitted()`：搜索模式下 Enter。
+- `Moved()`：查找栏模式下当前匹配改变。
+
+## 键盘操作
+
+搜索模式：Enter 提交，Escape 清空。查找栏模式：Enter 下一项，Shift+Enter 上一项，macOS 上 Cmd+G / Shift+Cmd+G、其他平台 F3 / Shift+F3（窗口级），循环到首尾；Escape 清空。
+
+## 限制
+
+- MyGo 单行编辑器把 Shift+Enter 当作普通提交且不公开修饰键（`editor.go:489`，`submitMods` 未导出），组件用 `HandleInput` 先截获 Shift+Enter。
+- 没有“完成/关闭”按钮；是否显示查找栏由调用方决定。

docs/components/029-checkbox.md

@@ -0,0 +1,51 @@
+# 029 Checkbox 复选框
+
+## 用途
+
+切换布尔值，支持选中、未选、半选；点击方框或标签都会切换。`CheckboxGroup` 提供组内全选（对应 MyGo CheckboxGroup）。基于 `ui.CheckboxBase`。
+
+## 最小示例
+
+```go
+mujica.CheckboxGroup(c, "Notifications", []mujica.CheckboxItem{
+	{Label: "Mail", Value: &mail},
+	{Label: "Calendar", Value: &calendar},
+}, mujica.CheckboxGroupOptions{})
+```
+
+签名：
+
+```go
+func Checkbox(c *ui.Context, value *bool, label string, opts CheckboxOptions) *ui.Element
+func CheckboxGroup(c *ui.Context, label string, items []CheckboxItem, opts CheckboxGroupOptions) InputResult
+```
+
+## 参数
+
+`CheckboxOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Indeterminate` | `bool` | `false` | 显示半选横线；此时点击总是变为选中。是否半选由调用方决定。 |
+| `Disabled` | `bool` | `false` | 禁用。 |
+
+`CheckboxItem`：`Label string`、`Value *bool`（必填）、`Disabled bool`。`CheckboxGroupOptions`：`Disabled bool`。`items` 为空时 panic。
+
+## 状态
+
+未选（Surface 底、ControlBorder 边）、悬停与按下（AccentText 边）、选中（酒红底、象牙白勾）、半选（酒红底、象牙白横线）、键盘聚焦（方框外焦点环）、禁用。行高不低于密度控件高度。
+
+全选框：全部选中为选中，部分选中为半选，全不选为未选。点击时若可用项未全选则全部勾选，否则全部清除；禁用项保持不变。
+
+## 事件
+
+- `Checkbox(...).Changed()`：用户切换了值。
+- `CheckboxGroup(...).Changed()`：全选或任一项被切换。
+
+## 键盘操作
+
+Tab 聚焦（每个复选框一个停靠点）；Space 切换。
+
+## 限制
+
+- MyGo 只有内部字段能把复选框报告为“mixed”（`access.go:307`，`checked` 未导出）。半选时组件在无障碍描述中加入“部分选中”，但角色状态仍报告为未选中。

docs/components/030-radio-group.md

@@ -0,0 +1,52 @@
+# 030 RadioGroup 单选组
+
+## 用途
+
+在一组选项中选一个，横向或纵向排列；选项值是任意可比较类型，作为稳定标识。基于 `ui.RadioGroup` 与 `ui.RadioBase`，整组是一个 Tab 停靠点。
+
+## 最小示例
+
+```go
+items := []mujica.RadioItem[string]{{Value: "s", Label: "Small"}, {Value: "m", Label: "Medium"}, {Value: "l", Label: "Large"}}
+if mujica.RadioGroup(c, &size, items, mujica.RadioGroupOptions{Label: "Size"}).Changed() {
+	fmt.Println("size", size)
+}
+```
+
+签名：`func RadioGroup[T comparable](c *ui.Context, value *T, items []RadioItem[T], opts RadioGroupOptions) InputResult`
+
+## 参数
+
+`RadioItem[T]`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Value` | `T` | 必填 | 稳定选项值；重复时 panic。 |
+| `Label` | `string` | `""` | 标签，点击标签也会选择。 |
+| `Disabled` | `bool` | `false` | 单项禁用，方向键跳过。 |
+
+`RadioGroupOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Horizontal` | `bool` | `false` | 横向排列。 |
+| `Label` | `string` | `""` | 组的无障碍名称。 |
+| `Disabled` | `bool` | `false` | 禁用整组。 |
+
+`value` 为 nil 或 `items` 为空时 panic。`*value` 不在选项中时没有选中项。
+
+## 状态
+
+未选（空心圆）、悬停与按下（AccentText 边）、选中（酒红实心圆与象牙白圆点）、键盘聚焦、禁用。
+
+## 事件
+
+`Changed()`：用户选择了另一个值（点击、Space 或方向键）。
+
+## 键盘操作
+
+Tab 进入组并落在已选项；Up/Down/Left/Right 移动并直接选择，循环，跳过禁用项；Home、End 选择首末可用项。
+
+## 限制
+
+- 方向键对横向与纵向组都同时响应上下左右（MyGo `RadioGroup` 固定使用 `Horizontal|Vertical`）。

docs/components/041-form.md

@@ -0,0 +1,59 @@
+# 041 Form
+
+表单。
+
+## 用途
+
+组合多个字段：注册字段、同步与调用方提供的异步校验、提交与重置、提交中防重入、提交失败时定位第一个错误字段。Form 不保存业务模型，不调用远程接口，也不做持久化；值始终由应用持有。
+
+## 最小示例
+
+```go
+var state mujica.FormState
+name := ""
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	res := mujica.Form(c, &state, mujica.FormOptions{}, func(f *mujica.FormScope) {
+		mujica.FormItem(f, "name", &name, mujica.FormItemOptions[string]{Label: "Name", Required: true}, func() *ui.Element {
+			return mujica.InputGroup(c, &name, mujica.InputGroupOptions{Invalid: state.Error("name") != ""}).Input
+		})
+	})
+	if res.Submitted() {
+		state.EndSubmit("") // after saving name
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `FormOptions.Horizontal` | `bool` | false | 标签放在控件左侧一列，右对齐（MyGo `ui.Form` 布局）。 |
+| `FormOptions.SubmitLabel` | `string` | 内置“Submit/提交” | 提交按钮文字。 |
+| `FormOptions.ResetLabel` | `string` | 内置“Reset/重置” | 重置按钮文字。 |
+| `FormItemOptions[T].Label` | `string` | 必填 | 字段标签；空值 panic。 |
+| `FormItemOptions[T].Required` | `bool` | false | 标记必填；零值、空字符串、空切片或空映射视为缺失。 |
+| `FormItemOptions[T].Description` | `string` | "" | 说明文字；异步校验进行中显示“Checking…”。 |
+| `FormItemOptions[T].Initial` | `T` | 零值 | 重置时写回的初始值。 |
+| `FormItemOptions[T].Validate` | `func(T) string` | nil | 同步校验，返回错误文字或 ""；跨字段规则在此读取其他值。 |
+| `FormItemOptions[T].Async` | `func(v T, version uint64)` | nil | 启动异步校验；完成后在界面线程调用 `FormState.Resolve(name, version, msg)`。 |
+
+## 状态
+
+默认；字段错误（触碰后或首次提交后才显示）；异步校验中（说明显示 Checking…）；提交中（提交按钮显示加载并阻止重复提交，重置禁用）；提交失败（表单级错误显示在按钮上方，保留全部值）。
+
+## 事件
+
+`FormParts.Submitted()`：全部校验通过的一次提交，处理完毕后调用 `FormState.EndSubmit(err)`。`FormParts.Reset()`：已恢复初始值并清除校验与提交状态。`FormState.Submit()` 可在 Enter 等处请求提交。`FormState.Error(name)` 返回当前应显示的错误，用于给控件设置 Invalid。
+
+## 键盘操作
+
+Tab / Shift+Tab 在字段间移动，离开字段即校验。提交失败后焦点移到第一个错误字段并滚动到可见处，同时向屏幕阅读器播报。点击标签聚焦控件。
+
+## 限制
+
+- 控件由调用方构建，`FormItem` 的 control 回调必须返回可获取焦点的元素，用于错误定位。
+- 校验在失焦与提交时触发；已触碰字段在值变化时重新同步校验，异步校验只在下一次失焦或提交时重跑。
+- 异步结果以版本号对齐：值变化后旧版本的 `Resolve` 返回 false 并被丢弃。`FormState` 的方法只能在界面线程调用，后台任务需经 `Window.Update` 回到界面线程。
+- 必填标记以“ *”附在标签文字后，屏幕阅读器会一起读出；MyGo 的 Field 标签不支持富文本，无法单独着色。

docs/components/042-form-field.md

@@ -0,0 +1,49 @@
+# 042 FormField
+
+表单字段。
+
+## 用途
+
+为单个控件提供标签、必填标记、说明与错误文字。标签通过 MyGo `ui.Field` 关联控件：屏幕阅读器以标签命名控件，并读出说明与错误；点击标签聚焦控件。
+
+## 最小示例
+
+```go
+email := ""
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.FormField(c, "Email", mujica.FormFieldOptions{Required: true, Description: "For receipts."}, func() {
+		mujica.InputGroup(c, &email, mujica.InputGroupOptions{})
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `label` | `string` | 必填 | 标签文字；空值 panic。 |
+| `FormFieldOptions.Required` | `bool` | false | 在标签后加“ *”。 |
+| `FormFieldOptions.Description` | `string` | "" | 控件下方的说明。 |
+| `FormFieldOptions.Error` | `string` | "" | 控件下方的错误，并把控件标记为无效。 |
+| `FormFieldOptions.Horizontal` | `bool` | false | 标签在左、控件在右。 |
+| `control` | `func()` | 必填 | 构建控件；其中第一个可获取焦点的元素即被关联的控件。 |
+
+## 状态
+
+默认、必填、带说明、错误；禁用由控件自身决定，标签随之变淡。
+
+## 事件
+
+无自身事件；事件来自内部控件。
+
+## 键盘操作
+
+Tab 直接到达控件；点击标签聚焦控件，或切换复选框、开关。
+
+## 限制
+
+- 标签、说明与错误文字由 MyGo `ui.Field` 绘制，使用主题颜色（文字、TextMuted、Danger）；字号与间距跟随 MyGo。
+- 错误只把边框染红的效果对 MyGo 自带输入框生效；MujicaUI 的 InputGroup 等需同时传入 `Invalid: true`。
+- 左右布局时多个字段需放在同一个 `ui.Form` 或 MujicaUI `Form(Horizontal)` 中才能对齐标签宽度；单独使用时只按自身标签宽度排列。

docs/components/043-input-group.md

@@ -0,0 +1,54 @@
+# 043 InputGroup
+
+输入组合。
+
+## 用途
+
+把单行输入框与前后缀文字、按钮放进同一个边框，例如网址前缀、单位、清空或搜索按钮。每个按钮保留独立焦点。
+
+## 最小示例
+
+```go
+site := ""
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	g := mujica.InputGroup(c, &site, mujica.InputGroupOptions{
+		Prefix: "https://", Label: "Site",
+		Buttons: []mujica.InputGroupButton{{Label: "Open"}},
+	})
+	if g.Clicked == 0 {
+		c.OpenURL("https://" + site)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `value` | `*string` | 必填 | 输入框的值。 |
+| `Prefix / Suffix` | `string` | "" | 输入框前后的固定文字。 |
+| `Buttons` | `[]InputGroupButton` | nil | 按钮：Label（必填，文字或无障碍名称）、Icon、IconOnly、Leading（放在输入框前）、Disabled。 |
+| `Placeholder` | `string` | "" | 占位文字。 |
+| `Label` | `string` | "" | 不在 FormField 内时为输入框命名。 |
+| `Disabled` | `bool` | false | 禁用整个组合。 |
+| `ReadOnly` | `bool` | false | 值显示为可选择、可复制、可聚焦的文字，不能修改；按钮仍可用。 |
+| `Invalid` | `bool` | false | 边框显示危险色。 |
+
+## 状态
+
+默认、悬停（边框加深）、聚焦（强调色边框与焦点环）、禁用、只读、错误。
+
+## 事件
+
+`InputGroupParts.Changed()` 值被编辑；`Submitted()` 在输入框中按 Enter；`Clicked` 为被点击按钮在 Buttons 中的下标，未点击为 -1。`Input` 为可聚焦的输入元素。
+
+## 键盘操作
+
+输入框与每个按钮都是独立的 Tab 停靠点；按钮响应 Enter 和 Space；输入框保留选择、剪贴板、撤销与输入法。
+
+## 限制
+
+- MyGo 没有公开的只读输入框，ReadOnly 改用可选择文字实现，宽度与输入框一致。
+- IconOnly 按钮必须提供 Icon，Label 作为无障碍名称；缺失时 panic。

docs/components/044-pin-input.md

@@ -0,0 +1,48 @@
+# 044 PinInput
+
+验证码输入。
+
+## 用途
+
+输入固定位数的数字验证码。值是字符串，保留前导零。
+
+## 最小示例
+
+```go
+code := ""
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.PinInput(c, &code, mujica.PinInputOptions{Length: 6}).Completed() {
+		fmt.Println("verify", code)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `value` | `*string` | 必填 | 当前数字串；含非数字或超出位数时 panic。 |
+| `Length` | `int` | 6 | 位数。 |
+| `Label` | `string` | 内置“Verification code/验证码” | 无障碍名称。 |
+| `Disabled` | `bool` | false | 禁用。 |
+| `Invalid` | `bool` | false | 格子边框显示危险色。 |
+
+## 状态
+
+默认、聚焦（当前格强调边框、焦点环与光标）、输入法组合中（当前格显示带下划线的组合文字）、禁用、错误。
+
+## 事件
+
+`PinInputParts.Changed()` 值改变；`Completed()` 在用户填满最后一格的那一帧为 true。
+
+## 键盘操作
+
+数字键依次填格；非数字被忽略；Backspace 清除最后一位；Cmd/Ctrl+V 或编辑菜单粘贴整段，取其中的数字填满各格。
+
+## 限制
+
+- 只支持数字。编辑按顺序进行：只能在末尾追加或删除，不能单独改中间某一格。
+- 输入法组合期间不提交、不跳格；组合结束后才写入值。
+- 整个组件是一个焦点停靠点，屏幕阅读器以文本框读出名称与“已输入 n / N 位”的说明。

docs/components/045-tags-input.md

@@ -0,0 +1,48 @@
+# 045 TagsInput
+
+标签输入。
+
+## 用途
+
+编辑一组不重复的标签，对应 MyGo 的 Token field。支持 Enter 或分隔符添加、整段粘贴拆分、去重、数量上限与添加前校验。
+
+## 最小示例
+
+```go
+tags := []string{"gothic"}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.TagsInput(c, &tags, mujica.TagsInputOptions{Max: 5, Placeholder: "Add a tag", Label: "Tags"})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `tags` | `*[]string` | 必填 | 标签列表。 |
+| `Max` | `int` | 0（不限） | 最多标签数；负数 panic。 |
+| `Separators` | `string` | ",;，；" 与换行、制表符 | 输入或粘贴时用于拆分的字符。 |
+| `Validate` | `func(string) string` | nil | 添加前校验，返回错误文字或 ""。 |
+| `Placeholder` | `string` | "" | 占位文字。 |
+| `Label` | `string` | "" | 不在 FormField 内时为输入框命名。 |
+| `Disabled` | `bool` | false | 禁用。 |
+| `Invalid` | `bool` | false | 边框显示危险色。 |
+
+## 状态
+
+默认、聚焦、错误（重复、超出上限、校验失败时显示具体原因并保留输入文字）、禁用。
+
+## 事件
+
+`TagsInputParts.Changed()` 添加或移除了标签；`Input` 为输入框元素。
+
+## 键盘操作
+
+Enter 或分隔符添加；输入框为空时 Backspace 移除最后一个标签；Tab 可到达每个标签的移除按钮，Enter/Space 移除。
+
+## 限制
+
+- 粘贴含分隔符的文本时，未通过检查的片段保留在输入框中，供用户修改。
+- MyGo 单行输入框会处理粘贴文本中的换行，换行能否作为分隔符取决于平台粘贴行为；逗号、分号总是有效。

docs/components/046-rating.md

@@ -0,0 +1,46 @@
+# 046 Rating
+
+评分。
+
+## 用途
+
+以星形显示和设置评分，支持半星等步长、只读展示和数值说明。
+
+## 最小示例
+
+```go
+stars := 3.5
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Rating(c, &stars, mujica.RatingOptions{Step: 0.5, ShowValue: true})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `value` | `*float64` | 必填 | 评分，0 到 Max。 |
+| `Max` | `int` | 5 | 星数；负数 panic。 |
+| `Step` | `float64` | 1 | 最小变化量，须整除 1（如 0.5、0.25）；否则 panic。 |
+| `ReadOnly` | `bool` | false | 只显示，可聚焦以便读出数值。 |
+| `Disabled` | `bool` | false | 禁用。 |
+| `Label` | `string` | 内置“Rating/评分” | 无障碍名称。 |
+| `ShowValue` | `bool` | false | 在星形右侧显示“3.5 / 5”。 |
+
+## 状态
+
+默认、悬停（预览指针处的数值）、按下拖动、聚焦（焦点环）、只读、禁用。
+
+## 事件
+
+`RatingParts.Changed()` 用户设置了新值；同值点击不触发。
+
+## 键盘操作
+
+→/↑ 增加一个步长，←/↓ 减少，Home 清零，End 满分。
+
+## 限制
+
+- 屏幕阅读器以滑块角色读出名称，数值通过说明“3.5 of 5”提供；MyGo 未公开为自定义元素设置数值范围的接口。

docs/components/047-color-picker.md

@@ -0,0 +1,45 @@
+# 047 ColorPicker
+
+颜色选择器。
+
+## 用途
+
+选择带透明度的颜色：色板按钮弹出面板，包含饱和度/亮度方块、色相与透明度滑块、HEX 与 RGB、透明度输入以及预设色。透明部分显示棋盘格。
+
+## 最小示例
+
+```go
+tint := ui.Hex("#7D2034")
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.ColorPicker(c, &tint, mujica.ColorPickerOptions{Label: "Tint"})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `color` | `*ui.Color` | 必填 | 当前颜色。 |
+| `Presets` | `[]ui.Color` | 内置 12 色宫廷色板 | 预设色。 |
+| `Label` | `string` | 内置“Color/颜色” | 按钮的无障碍名称。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+默认、悬停、聚焦、展开、输入无效（对应输入框边框变红并显示格式说明，颜色不变）、预设选中（边框加勾选标记）、禁用。
+
+## 事件
+
+`ColorPickerParts.Changed()` 用户选择了新颜色；`Trigger` 为按钮元素。
+
+## 键盘操作
+
+Enter/Space 打开；打开后焦点在方块上，方向键调整饱和度与亮度；Tab 依次到达色相、透明度滑块（方向键、Home、End）、HEX、R、G、B、A 输入框与预设色；Escape 或点击外部关闭并把焦点还给按钮。
+
+## 限制
+
+- HEX 接受 RGB、RRGGBB、RRGGBBAA，可带或不带 #；RGB 为 0–255 整数，透明度为 0–100。无效输入保留在输入框中直到失焦，不修改颜色。
+- 色谱渐变是 PRD 允许的例外。
+- 弹层位置由 MyGo PopoverBase 决定，空间不足时显示在按钮上方。

docs/components/048-file-picker.md

@@ -0,0 +1,52 @@
+# 048 FilePicker
+
+文件选择。
+
+## 用途
+
+调用 MyGo 的系统文件或文件夹选择对话框（`mygo.Dialog.Open`），支持单选、多选与扩展名筛选，只返回所选路径。
+
+## 最小示例
+
+```go
+var paths []string
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.FilePicker(c, &paths, mujica.FilePickerOptions{
+		Multiple: true,
+		Filters:  []mygo.FileFilter{{Name: "Scores", Extensions: []string{"pdf", "mid"}}},
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `paths` | `*[]string` | 必填 | 所选路径；取消时不变。 |
+| `Directory` | `bool` | false | 选择文件夹。 |
+| `Multiple` | `bool` | false | 允许多选。 |
+| `Filters` | `[]mygo.FileFilter` | nil | 扩展名筛选，扩展名不带点；带点时 panic。 |
+| `Title` | `string` | "" | 对话框标题。 |
+| `Label` | `string` | 内置“Choose file…/选择文件…” | 按钮文字。 |
+| `Parent` | `*mygo.Window` | nil | 附着的窗口（macOS 显示为表单）。 |
+| `Disabled` | `bool` | false | 禁用。 |
+
+## 状态
+
+默认、对话框打开中（按钮显示加载并阻止重复打开）、已选择（列出文件名与所在目录）、对话框失败（危险色说明）、禁用。
+
+## 事件
+
+`FilePickerParts.Changed()` 选中了新路径；`Canceled()` 用户取消，不视为错误。
+
+## 键盘操作
+
+Enter/Space 打开系统对话框；对话框内的键盘操作由系统提供。
+
+## 限制
+
+- 对话框为系统样式，不换肤。
+- 对话框在后台 goroutine 中等待，结果经 `Context.Invalidate` 回到界面线程；需要应用已通过 `mygo.App.Run` 启动，无窗口测试中无法打开真实对话框。
+- 不读取文件内容。

docs/components/049-file-drop-zone.md

@@ -0,0 +1,49 @@
+# 049 FileDropZone
+
+文件拖放区。
+
+## 用途
+
+接收从系统拖入或通过“浏览…”选择的文件，检查类型、数量和大小，显示文件列表与错误，可逐项移除。不上传，不读取内容。
+
+## 最小示例
+
+```go
+var files []mujica.DroppedFile
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.FileDropZone(c, &files, mujica.FileDropZoneOptions{
+		Extensions: []string{"png", "jpg"}, MaxFiles: 3, MaxSize: 5 << 20,
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `files` | `*[]DroppedFile` | 必填 | 已接受的文件（Path、Size）。 |
+| `Extensions` | `[]string` | nil（不限） | 允许的扩展名，不带点，不区分大小写。 |
+| `MaxFiles` | `int` | 0（不限） | 列表最多文件数。 |
+| `MaxSize` | `int64` | 0（不限） | 单个文件的最大字节数。 |
+| `Hint` | `string` | 内置“Drop files here/将文件拖到此处” | 提示文字。 |
+| `Disabled` | `bool` | false | 禁用拖放、浏览与移除。 |
+
+## 状态
+
+默认、文件拖到上方（选中底色与强调色虚线边框）、检查中（列表显示“Checking…”）、已接受、被拒绝（危险色图标与具体原因）、禁用。
+
+## 事件
+
+`FileDropZoneParts.Changed()` 添加或移除了文件。被拒绝的条目只显示在组件内，可单独关闭。
+
+## 键盘操作
+
+Tab 到达“浏览…”与每个移除按钮；拖放需要指针，键盘用户通过“浏览…”添加文件。
+
+## 限制
+
+- 文件大小通过后台 goroutine 中的 `os.Stat` 获取，不阻塞界面线程；文件夹、无法读取的路径会被拒绝。
+- 重复路径静默忽略。
+- MyGo 的无窗口测试器不能模拟系统拖放，自动测试通过“浏览…”路径覆盖同一检查流程。

docs/components/050-transfer.md

@@ -0,0 +1,46 @@
+# 050 Transfer
+
+穿梭框。
+
+## 用途
+
+在左右两个列表间移动条目，选出一个子集。两侧各有搜索、复选与全选，中间按钮批量移动。以稳定 ID 保存状态。
+
+## 最小示例
+
+```go
+chosen := []string{"uika"}
+items := []mujica.TransferItem{{ID: "uika", Label: "Uika"}, {ID: "mutsumi", Label: "Mutsumi"}, {ID: "nyamu", Label: "Nyamu", Disabled: true}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Transfer(c, &chosen, items, mujica.TransferOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `target` | `*[]string` | 必填 | 右侧已选条目的 ID，按加入顺序；含未知 ID 时 panic。 |
+| `items` | `[]TransferItem` | 必填 | 全部条目：ID（唯一、非空）、Label、Disabled。 |
+| `SourceTitle / TargetTitle` | `string` | 内置“Available/可选”“Chosen/已选” | 两侧标题。 |
+| `Height` | `float32` | 240 | 列表高度（DIP）。 |
+| `Disabled` | `bool` | false | 禁用整个组件。 |
+
+## 状态
+
+默认、悬停、勾选（底色加勾选标记）、半选（全选框显示减号）、禁用条目（不可勾选、不随全选移动）、空列表、无搜索结果、禁用。
+
+## 事件
+
+`TransferParts.Changed()` 有条目移动。
+
+## 键盘操作
+
+Tab 进入列表，↑/↓ 在条目间移动，Space 勾选；Tab 到达全选框、搜索框与移动按钮。
+
+## 限制
+
+- 条目逐项创建，适合数百条以内；大数据量请使用虚拟化列表组合。
+- 全选只作用于当前搜索结果中的可用条目。

docs/components/051-calendar.md

@@ -0,0 +1,55 @@
+# 051 Calendar · 日历
+
+## 用途
+
+在页面中直接显示一个月份，用于选择单个日期。支持今日标记、不可选日期与周起始日配置。
+
+## 最小示例
+
+```go
+day := mujica.Date{Year: 2026, Month: time.October, Day: 5}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.Calendar(c, &day, mujica.CalendarOptions{WeekStart: mujica.WeekStartMonday}).Changed() {
+		fmt.Println("chosen", day)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func Calendar(c *ui.Context, value *Date, opts CalendarOptions) DateTimeResult`，返回值嵌入 `*ui.Element`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Min` | `Date` | 零值 | 最早可选日期；零值不限制。 |
+| `Max` | `Date` | 零值 | 最晚可选日期；零值不限制。 |
+| `DisableDate` | `func(Date) bool` | nil | 返回 true 的日期不可选，显示删除线。 |
+| `WeekStart` | `WeekStart` | `WeekStartLocale` | 首列星期：跟随语言（zh-CN 周一、en-US 周日），或 `WeekStartSunday`/`WeekStartMonday`/`WeekStartSaturday`。 |
+| `Today` | `Date` | 零值（系统时钟） | 标记为今天的日期：加粗并在下方绘制菱形。 |
+| `Disabled` | `bool` | false | 禁用整个日历：不能翻页、不能选择，退出 Tab 序列。 |
+| `Label` | `string` | 内置“日历” | 辅助技术读出的名称。 |
+
+## 状态
+
+默认、悬停、按下、聚焦（键盘焦点环）、选中（酒红填充 + 单选语义）、今日（加粗 + 菱形）、不可选（删除线并由 MyGo 置灰）、非本月（弱化文字）、禁用。
+
+## 事件
+
+`Calendar(...).Changed()` 在用户选择了与原值不同的日期的那一帧返回 true，`*value` 已更新。翻月不触发事件。
+
+## 键盘操作
+
+- Tab：进入日期格，落在已选日期或上次聚焦的日期。
+- ←/→：前后一天；↑/↓：前后一周（自动跳过不可选日期，最多 31 天）。
+- PageUp/PageDown：上/下一月；Shift+PageUp/PageDown：上/下一年。
+- Home/End：本月第一天/最后一天。
+- Enter/Space：选择当前日期。
+
+## 限制
+
+- 不可选日期不能获得焦点；若方向键 31 天内找不到可选日期，视图会翻页但焦点停在原处。
+- MyGo 的 `ui.Calendar` 固定周一起始、只有英文且不支持禁用日期（ui/date.go:85-160），因此本组件基于 `RadioBase` 自绘网格，不复用 `ui.Calendar`。
+- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
+- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。

docs/components/052-date-picker.md

@@ -0,0 +1,59 @@
+# 052 DatePicker · 日期选择器
+
+## 用途
+
+可键入的日期输入框，带日历弹层。用于表单中录入单个日期。
+
+## 最小示例
+
+```go
+due := mujica.Date{Year: 2026, Month: time.October, Day: 5}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	opts := mujica.DatePickerOptions{Label: "Due date", Clearable: true,
+		Min: mujica.Date{Year: 2026, Month: time.January, Day: 1}}
+	if mujica.DatePicker(c, &due, opts).Changed() {
+		fmt.Println("due", due)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func DatePicker(c *ui.Context, value *Date, opts DatePickerOptions) DateTimeResult`，返回值嵌入 `*ui.Element`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Layout` | `string` | `2006-01-02` | Go 时间布局，用于显示与解析输入。 |
+| `Min` | `Date` | 零值 | 最早可接受日期。 |
+| `Max` | `Date` | 零值 | 最晚可接受日期。 |
+| `DisableDate` | `func(Date) bool` | nil | 不可选日期；键入此类日期会报告错误。 |
+| `WeekStart` | `WeekStart` | `WeekStartLocale` | 弹层日历的周起始日。 |
+| `Today` | `Date` | 零值（系统时钟） | 弹层日历中的今日标记；空值时弹层打开到此月份。 |
+| `Clearable` | `bool` | false | 显示清空按钮；清空输入后提交表示“无日期”。 |
+| `Placeholder` | `string` | 内置“选择日期” | 空输入框的占位文字。 |
+| `Disabled` | `bool` | false | 禁用输入与弹层。 |
+| `Label` | `string` | 占位文字 | 辅助技术名称。 |
+
+## 状态
+
+默认、悬停（边框加深）、聚焦（焦点色边框）、错误（危险色边框 + 下方说明，输入保留）、禁用。弹层内日历状态同 Calendar。
+
+## 事件
+
+`Changed()`：键入后按 Enter 或离开输入框并解析成功、在日历中选择、或点击清空导致值变化时为 true。
+
+## 键盘操作
+
+- 键入日期后 Enter 提交；Tab 离开时也会提交。
+- ↓ 或 Alt+↓：打开日历；日历内按键同 Calendar，Enter 选择后关闭并写入。
+- Escape：关闭日历，不改值。
+
+## 限制
+
+- 无效或越界的输入（如 2026-02-30）显示具体错误并保留原文，不会被修正为相邻日期。
+- MyGo 的 `ui.DateInput` 固定格式且不可键入（ui/date.go:13），因此本组件组合 `TextInputBase` 与自绘日历弹层（`PopoverBase`）。
+- 暂不提供只读模式：MyGo v0.2.10 未公开 TextInputBase 的只读开关。
+- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
+- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。

docs/components/053-date-range-picker.md

@@ -0,0 +1,57 @@
+# 053 DateRangePicker · 日期范围选择器
+
+## 用途
+
+在弹层中先选开始日期、再选结束日期，悬停时预览范围，确认后写入。
+
+## 最小示例
+
+```go
+var stay mujica.DateRange
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	r := mujica.DateRangePicker(c, &stay, mujica.DateRangePickerOptions{Label: "Stay"})
+	if r.Changed() {
+		fmt.Println("stay", stay.Start, stay.End, stay.Days())
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func DateRangePicker(c *ui.Context, value *DateRange, opts DateRangePickerOptions) DateTimeResult`，返回值嵌入 `*ui.Element`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Layout` | `string` | `2006-01-02` | 触发器与摘要中的日期格式。 |
+| `Min` | `Date` | 零值 | 两端最早日期。 |
+| `Max` | `Date` | 零值 | 两端最晚日期。 |
+| `DisableDate` | `func(Date) bool` | nil | 不可选日期；范围内包含此类日期时拒绝并提示。 |
+| `WeekStart` | `WeekStart` | `WeekStartLocale` | 周起始日。 |
+| `Today` | `Date` | 零值（系统时钟） | 今日标记与空值时的起始月份。 |
+| `Disabled` | `bool` | false | 禁用。 |
+| `Label` | `string` | 内置“日期范围” | 辅助技术名称。 |
+
+## 状态
+
+触发器：默认、悬停、聚焦、禁用。弹层：起止日期酒红填充，中间日期浅色带；选择结束前随指针或焦点预览范围；错误说明；“确定”在两端选齐前禁用。
+
+## 事件
+
+`Changed()`：点击“确定”或“清空”使值改变时为 true。`Cancelled()`：按 Escape、点击“取消”或点击弹层外关闭、草稿被丢弃时为 true。
+
+## 键盘操作
+
+- Enter/Space/↓：打开弹层。
+- 日历内方向键移动，Enter 依次选择开始与结束。
+- 早于开始日期的选择会重新开始范围。
+- Tab 到“清空”“取消”“确定”。
+- Escape：放弃草稿。
+
+## 限制
+
+- 弹层一次显示一个月；跨月范围通过翻页完成。
+- `DateRange` 为闭区间，`Days()` 计入两端。
+- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
+- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。

docs/components/054-time-picker.md

@@ -0,0 +1,59 @@
+# 054 TimePicker · 时间选择器
+
+## 用途
+
+分段编辑时、分、秒的时间输入，可在弹层列表中选择；支持 12/24 小时制、步长和范围。
+
+## 最小示例
+
+```go
+alarm := mujica.TimeOfDay{Hour: 7, Minute: 30}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	opts := mujica.TimePickerOptions{Label: "Alarm", Hour12: true, MinuteStep: 5}
+	if mujica.TimePicker(c, &alarm, opts).Changed() {
+		fmt.Println("alarm", alarm)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func TimePicker(c *ui.Context, value *TimeOfDay, opts TimePickerOptions) DateTimeResult`，返回值嵌入 `*ui.Element`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Seconds` | `bool` | false | 显示并编辑秒。 |
+| `Hour12` | `bool` | false | 12 小时制，附加上午/下午段。 |
+| `MinuteStep` | `int` | 0（即 1） | 分钟步长，必须整除 60。 |
+| `SecondStep` | `int` | 0（即 1） | 秒步长，必须整除 60。 |
+| `Min` | `TimeOfDay` | 00:00:00 | 最早时间。 |
+| `Max` | `TimeOfDay` | 零值（即 23:59:59） | 最晚时间。 |
+| `Disabled` | `bool` | false | 禁用。 |
+| `Label` | `string` | 空 | 组名；各段名称为“Label: 时/分/秒”。 |
+
+## 状态
+
+默认、悬停、聚焦段（酒红填充）、错误（危险色边框 + 说明，草稿保留）、禁用。弹层列表中超出范围的项禁用。
+
+## 事件
+
+`Changed()`：编辑后的时间合法（在范围内且符合步长）并与原值不同时为 true。不合法时不写入，显示错误。
+
+## 键盘操作
+
+- Tab：进入时间段（整组一个 Tab 停靠点）。
+- ←/→：切换时、分、秒、上午/下午。
+- ↑/↓：按步长增减，整圈循环。
+- 数字键：直接键入，时完成后自动跳到分。
+- A/P：设置上午/下午。
+- Alt+↓ 或时钟按钮：打开列表弹层；Escape 关闭。
+
+## 限制
+
+- 超出范围或不符合步长的时间会提示，不会被自动夹取或取整。
+- 段顺序固定为“时:分:秒 上午/下午”，zh-CN 下上午/下午也位于末尾。
+- MyGo 的 `ui.TimeInput` 只有时分且无 12 小时制、步长和范围（ui/timeinput.go:18），因此本组件自绘分段。
+- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
+- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。

docs/components/055-time-range-picker.md

@@ -0,0 +1,55 @@
+# 055 TimeRangePicker · 时间范围选择器
+
+## 用途
+
+编辑开始与结束时间，校验顺序；跨午夜必须显式开启。
+
+## 最小示例
+
+```go
+shift := mujica.TimeRange{Start: mujica.TimeOfDay{Hour: 22}, End: mujica.TimeOfDay{Hour: 6}}
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	opts := mujica.TimeRangePickerOptions{Label: "Night shift", AllowOvernight: true}
+	if mujica.TimeRangePicker(c, &shift, opts).Changed() {
+		fmt.Println("shift", shift.Start, shift.End, shift.Overnight())
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func TimeRangePicker(c *ui.Context, value *TimeRange, opts TimeRangePickerOptions) DateTimeResult`，返回值嵌入 `*ui.Element`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Seconds` | `bool` | false | 显示秒。 |
+| `Hour12` | `bool` | false | 12 小时制。 |
+| `MinuteStep` | `int` | 0（即 1） | 分钟步长。 |
+| `SecondStep` | `int` | 0（即 1） | 秒步长。 |
+| `Min` | `TimeOfDay` | 00:00:00 | 两端最早时间。 |
+| `Max` | `TimeOfDay` | 零值（即 23:59:59） | 两端最晚时间。 |
+| `AllowOvernight` | `bool` | false | 允许结束早于开始，表示次日结束，并显示“次日”。 |
+| `Disabled` | `bool` | false | 禁用。 |
+| `Label` | `string` | 空 | 整组名称。 |
+
+## 状态
+
+同 TimePicker；范围不合法时两端都显示错误边框；跨午夜时显示“+1 day / 次日”。
+
+## 事件
+
+`Changed()`：两端都合法且顺序正确、与原值不同时为 true。
+
+## 键盘操作
+
+- 两端各自按 TimePicker 操作；Tab 从开始移到结束。
+
+## 限制
+
+- 未开启 `AllowOvernight` 时传入跨午夜的值会 panic（编程错误）。
+- 开始等于结束视为错误。
+- `TimeRange.Overnight()` 报告是否跨午夜。
+- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
+- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。

docs/components/056-date-time-picker.md

@@ -0,0 +1,62 @@
+# 056 DateTimePicker · 日期时间选择器
+
+## 用途
+
+在调用方指定的时区中编辑日期和时间，确认后写入 `time.Time`。
+
+## 最小示例
+
+```go
+tokyo, err := time.LoadLocation("Asia/Tokyo")
+if err != nil {
+	panic(err)
+}
+var meeting time.Time
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	opts := mujica.DateTimePickerOptions{Label: "Meeting", Location: tokyo, MinuteStep: 15}
+	if mujica.DateTimePicker(c, &meeting, opts).Changed() {
+		fmt.Println("meeting", meeting)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func DateTimePicker(c *ui.Context, value *time.Time, opts DateTimePickerOptions) DateTimeResult`，返回值嵌入 `*ui.Element`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Location` | `*time.Location` | 必填 | 用户编辑所用时区；为 nil 时 panic。 |
+| `Min` | `time.Time` | 零值 | 最早时刻。 |
+| `Max` | `time.Time` | 零值 | 最晚时刻。 |
+| `Seconds` | `bool` | false | 显示秒。 |
+| `Hour12` | `bool` | false | 12 小时制。 |
+| `MinuteStep` | `int` | 0（即 1） | 分钟步长。 |
+| `WeekStart` | `WeekStart` | `WeekStartLocale` | 周起始日。 |
+| `Today` | `Date` | 零值（系统时钟） | 今日标记与空值时的默认日期。 |
+| `Disabled` | `bool` | false | 禁用。 |
+| `Label` | `string` | 内置占位文字 | 辅助技术名称。 |
+
+## 状态
+
+触发器显示该时区下的时间与时区缩写。弹层：日历、时间段、时区名、错误说明、“取消/确定”。
+
+## 事件
+
+`Changed()`：确认且时刻改变时为 true，写入的值位于 `Location`。`Cancelled()`：取消、Escape 或点击外部关闭时为 true。
+
+## 键盘操作
+
+- Enter/Space/↓：打开。
+- 日历与时间段按键同 DatePicker、TimePicker。
+- Tab 到“取消”“确定”。
+- Escape：取消。
+
+## 限制
+
+- 夏令时跳过的时间（如纽约 2026-03-08 02:30）和重复的时间（如 2026-11-01 01:30）都会提示，不会自动移到相邻时刻或选择其中之一。
+- 空值（零 `time.Time`）打开时默认今天 00:00。
+- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
+- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。

docs/components/057-month-picker.md

@@ -0,0 +1,55 @@
+# 057 MonthPicker · 月份选择器
+
+## 用途
+
+按年份分页选择月份。
+
+## 最小示例
+
+```go
+var month mujica.YearMonth
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	opts := mujica.MonthPickerOptions{Label: "Billing month", Clearable: true}
+	if mujica.MonthPicker(c, &month, opts).Changed() {
+		fmt.Println("month", month)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func MonthPicker(c *ui.Context, value *YearMonth, opts MonthPickerOptions) DateTimeResult`，返回值嵌入 `*ui.Element`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Min` | `YearMonth` | 零值 | 最早月份。 |
+| `Max` | `YearMonth` | 零值 | 最晚月份。 |
+| `DisableMonth` | `func(YearMonth) bool` | nil | 不可选月份。 |
+| `Clearable` | `bool` | false | 有值时显示清空按钮。 |
+| `Today` | `Date` | 零值（系统时钟） | 标记当前月份。 |
+| `Disabled` | `bool` | false | 禁用。 |
+| `Label` | `string` | 内置“选择月份” | 辅助技术名称。 |
+
+## 状态
+
+默认、悬停、聚焦、选中（酒红填充）、当前月（加粗 + 菱形）、不可选（删除线）、禁用。
+
+## 事件
+
+`Changed()`：选择或清空导致值变化时为 true。
+
+## 键盘操作
+
+- Enter/Space/↓：打开。
+- ←/→：前后一月；↑/↓：前后三月（一行）。
+- PageUp/PageDown：上/下一年。
+- Home/End：一月/十二月。
+- Enter：选择并关闭；Escape：关闭。
+
+## 限制
+
+- 键盘移到不可选月份时焦点保持在原处，可继续移动。
+- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
+- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。

docs/components/058-year-picker.md

@@ -0,0 +1,55 @@
+# 058 YearPicker · 年份选择器
+
+## 用途
+
+按十年分页浏览并选择年份。
+
+## 最小示例
+
+```go
+year := 2026
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	opts := mujica.YearPickerOptions{Label: "Vintage", Min: 1990, Max: 2030}
+	if mujica.YearPicker(c, &year, opts).Changed() {
+		fmt.Println("year", year)
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+## 参数
+
+`func YearPicker(c *ui.Context, value *int, opts YearPickerOptions) DateTimeResult`，返回值嵌入 `*ui.Element`。
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Min` | `int` | 0 | 最早年份；0 不限制。 |
+| `Max` | `int` | 0 | 最晚年份；0 不限制。 |
+| `DisableYear` | `func(int) bool` | nil | 不可选年份。 |
+| `Clearable` | `bool` | false | 有值时显示清空按钮。 |
+| `Today` | `Date` | 零值（系统时钟） | 标记当前年份。 |
+| `Disabled` | `bool` | false | 禁用。 |
+| `Label` | `string` | 内置“选择年份” | 辅助技术名称。 |
+
+## 状态
+
+默认、悬停、聚焦、选中、当前年、不可选、相邻十年（弱化）、禁用。
+
+## 事件
+
+`Changed()`：选择或清空导致值变化时为 true。`*value` 为 0 表示未选择。
+
+## 键盘操作
+
+- Enter/Space/↓：打开。
+- ←/→：前后一年；↑/↓：前后三年。
+- PageUp/PageDown：上/下一个十年。
+- Home/End：页首/页尾。
+- Enter：选择并关闭；Escape：关闭。
+
+## 限制
+
+- 只支持公元 1 年及以后；值为负数时 panic。
+- 日期与时间值不带时区：`Date`、`YearMonth`、`TimeOfDay` 只保存日历字段，组件内部计算不做 UTC 转换。
+- `Today` 为零值时读取 `c.Now()`（系统本地时区）；需要固定“今天”（测试、跨时区应用）时显式传入。

docs/components/059-tabs.md

@@ -0,0 +1,63 @@
+# 059 Tabs 标签页
+
+## 用途
+
+在同一区域内切换若干面板。标签列表与当前标签的面板一起构建；支持横向与纵向布局、禁用项和溢出滚动。Tabs 是视觉回归基准组件，快照覆盖三种密度。
+
+## 最小示例
+
+```go
+mujica.Tabs(c, &tab, []mujica.Tab{
+	{Label: "General", Panel: func() { ui.Text(c, "General settings") }},
+	{Label: "Fonts", Icon: icons.Must("italic"), Panel: func() { ui.Text(c, "Fonts") }},
+	{Label: "Archive", Disabled: true},
+}, mujica.TabsOptions{Label: "Settings"})
+```
+
+签名：`func Tabs(c *ui.Context, selected *int, tabs []Tab, opts TabsOptions) TabsResult`
+
+## 参数
+
+`selected`：当前标签下标（从 0 开始）。越界或指向禁用标签时 panic。`tabs` 为空时 panic。
+
+`Tab`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Label` | `string` | 必填 | 标签文字，也是面板的无障碍名称；为空时 panic。 |
+| `Icon` | `*ui.SVG` | nil | 标签文字前的 16 DIP 图标。 |
+| `Disabled` | `bool` | false | 禁用：不可点击、不进入方向键序列。 |
+| `Panel` | `func()` | nil | 选中时构建的面板内容；nil 显示空面板。 |
+
+`TabsOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Vertical` | `bool` | false | 标签竖排在左侧，面板在右侧。 |
+| `Label` | `string` | "" | 标签列表的无障碍名称。 |
+
+返回 `TabsResult`，内嵌包含标签与面板的 `*ui.Element`。
+
+## 状态
+
+- 选中：Selection 背景、2 DIP AccentText 边线（横向在底边，纵向在右边）、600 字重，三者同时标记。
+- 悬停：SurfaceHover 背景；按下：Selection 背景。
+- 焦点：2 DIP Focus 焦点环，外留 2 DIP。
+- 禁用：MyGo 统一降低不透明度，不响应指针与键盘。
+- 溢出：标签条横向（纵向时竖向）滚动；键盘或点击切换后，选中标签滚入视野。
+
+## 事件
+
+- `Changed()`：本帧用户选择了新标签（点击或方向键）。
+
+## 键盘操作
+
+- Tab：进入标签列表，落在当前标签；再按 Tab 离开。
+- ←/→、↑/↓：选择上一个/下一个可用标签，跳过禁用项，首尾循环；焦点随选择移动。
+- Home / End：第一个 / 最后一个可用标签。
+
+## 限制
+
+- MyGo `TabsBase` 的方向键不知道禁用项（`ui/base.go:192` 直接选择 i±1）。本组件只把可用标签交给 `TabsBase`，禁用标签以普通 `RoleTab` 行显示，因此禁用标签不在 MyGo 的标签计数内。
+- MyGo 没有 tabpanel 角色与 aria-controls 式关联；面板以 `RoleGroup` 呈现，名称取自所选标签。
+- 不提供标签关闭、拖动排序。

docs/components/060-segmented-control.md

@@ -0,0 +1,55 @@
+# 060 SegmentedControl 分段控件
+
+## 用途
+
+在少量互斥选项之间切换视图或范围，如“日 / 周 / 月”或“列表 / 网格”。基于 MyGo `SegmentedBase`，辅助技术看到单选组。
+
+## 最小示例
+
+```go
+mujica.SegmentedControl(c, &view, []mujica.Segment{
+	{Label: "List", Icon: icons.Must("list"), HideLabel: true},
+	{Label: "Grid", Icon: icons.Must("layout-grid"), HideLabel: true},
+}, mujica.SegmentedControlOptions{Label: "View"})
+```
+
+签名：`func SegmentedControl(c *ui.Context, selected *int, segments []Segment, opts SegmentedControlOptions) *ui.Element`
+
+## 参数
+
+`selected`：当前分段下标；越界时 panic。`segments` 为空时 panic。
+
+`Segment`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Label` | `string` | 必填 | 分段文字与无障碍名称；为空时 panic。 |
+| `Icon` | `*ui.SVG` | nil | 文字前的图标。 |
+| `HideLabel` | `bool` | false | 只显示图标，`Label` 作为名称与提示文字；没有 `Icon` 时 panic。 |
+
+`SegmentedControlOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Equal` | `bool` | false | 所有分段等宽（取最宽者）；否则按内容自适应。 |
+| `Label` | `string` | "" | 单选组的无障碍名称。 |
+| `Disabled` | `bool` | false | 整组禁用。 |
+
+## 状态
+
+- 选中：Accent 填充、OnAccent 文字、600 字重。
+- 悬停 SurfaceHover，按下 Selection；焦点环 2 DIP。
+- 禁用：整组降低不透明度，点击与方向键不改变值。
+
+## 事件
+
+- 返回元素的 `Changed()`：本帧用户选择了新分段。
+
+## 键盘操作
+
+- Tab：进入控件，落在当前分段（一个 Tab 停靠点）。
+- 方向键：选择上一个/下一个分段并循环；Home / End 到两端。
+
+## 限制
+
+- 不支持单个分段禁用：MyGo `SegmentedBase` 的焦点组在方向键移动时直接点击目标分段。

docs/components/061-breadcrumb.md

@@ -0,0 +1,57 @@
+# 061 Breadcrumb 面包屑
+
+## 用途
+
+显示当前位置的层级路径。最后一项为当前页（非链接），前面各项可点击返回；层级过多时中间项折叠到“…”菜单；过长名称以省略号截断，悬停显示完整名称。
+
+## 最小示例
+
+```go
+if i, ok := mujica.Breadcrumb(c, path, mujica.BreadcrumbOptions{}).Chosen(); ok {
+	path = path[:i+1]
+}
+```
+
+签名：`func Breadcrumb(c *ui.Context, items []BreadcrumbItem, opts BreadcrumbOptions) BreadcrumbResult`
+
+## 参数
+
+`items` 为空时 panic。
+
+`BreadcrumbItem`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Label` | `string` | 必填 | 名称；为空时 panic。 |
+| `Icon` | `*ui.SVG` | nil | 名称前的 14 DIP 图标。 |
+
+`BreadcrumbOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `MaxItems` | `int` | 0（即 4） | 最多显示的项数；超出时保留第一项和最后 `MaxItems-2` 项，其余折叠。小于 3 时 panic。 |
+| `MaxItemWidth` | `float32` | 0（即 160 DIP） | 单项文字最大宽度，超出以省略号截断。 |
+| `Label` | `string` | 内置“路径导航” | 整组的无障碍名称。 |
+
+返回 `BreadcrumbResult`，内嵌 `*ui.Element`。
+
+## 状态
+
+- 链接：TextMuted 文字，悬停 SurfaceHover 背景与 Text 文字，焦点环 2 DIP。
+- 当前项：Text 文字、600 字重，无障碍名称附“当前页”。
+- 分隔：旧金（Ornament）小箭头，不进入无障碍树。
+- 折叠按钮“…”：打开弹层列出被折叠的项，弹层打开时焦点在第一项。
+
+## 事件
+
+- `Chosen() (int, bool)`：本帧被激活的项下标（含折叠菜单中的项）。组件不修改路径，由调用方处理。
+
+## 键盘操作
+
+- Tab / Shift+Tab：在各链接与折叠按钮之间移动；Enter 或 Space 激活。
+- 折叠菜单：Tab 在项之间移动，Enter 选择，Escape 关闭并把焦点还给“…”按钮。
+
+## 限制
+
+- 完整名称提示对每一项都提供，MyGo 不报告文字是否被截断。
+- 未复用 MyGo `ui.Breadcrumbs`：它不支持折叠与提示，本组件用 `ButtonBase`、`PopoverBase` 组合实现。

docs/components/062-pagination.md

@@ -0,0 +1,53 @@
+# 062 Pagination 分页
+
+## 用途
+
+在分页数据之间移动：页码、上一页、下一页、页容量选择与跳页。总数变化后，超出范围的页码自动修正到最后一页并报告变化。
+
+## 最小示例
+
+```go
+if mujica.Pagination(c, &page, &size, mujica.PaginationOptions{Total: 420, PageSizes: []int{10, 20, 50}, Jump: true}).Changed() {
+	load(page, size)
+}
+```
+
+签名：`func Pagination(c *ui.Context, page, pageSize *int, opts PaginationOptions) PaginationResult`
+
+## 参数
+
+`page`：当前页，从 1 开始；每帧被限制在 `[1, 总页数]`。`pageSize`：每页条数，必须为正，否则 panic。
+
+`PaginationOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Total` | `int` | 0 | 记录总数；为负 panic。为 0 时仍显示 1 页。 |
+| `PageSizes` | `[]int` | nil | 可选的页容量；nil 隐藏选择器。非 nil 时须包含 `*pageSize`，否则 panic。 |
+| `Jump` | `bool` | false | 显示跳页输入框。 |
+| `Siblings` | `int` | 0（即 1） | 当前页两侧显示的页码数；为负 panic。 |
+| `Disabled` | `bool` | false | 整体禁用。 |
+
+返回 `PaginationResult`，内嵌 `*ui.Element`。
+
+## 状态
+
+- 当前页：Accent 填充、OnAccent 文字、600 字重，名称附“当前”。
+- 页码按钮：Border 细边框，悬停 SurfaceHover 与 ControlBorder 边框；首页时“上一页”禁用，末页时“下一页”禁用。
+- 页码多时首尾保留，中间以“…”省略，按钮数固定为 `2×Siblings+5`，位置稳定。
+- 跳页错误：输入非数字或超出范围时边框变为 Danger，并在旁显示有效范围；输入保留，可直接修改。
+- 修改页容量时，保持原页第一条记录可见。
+
+## 事件
+
+- `Changed()`：本帧页码或页容量改变（用户操作或总数变化导致的修正）。
+
+## 键盘操作
+
+- 页码按钮组是一个 Tab 停靠点：←/→ 移动，Home / End 到两端，Enter 或 Space 跳到该页。
+- 页容量：↑/↓ 打开并移动，Enter 选择，Escape 关闭。
+- 跳页框：输入页码后按 Enter。
+
+## 限制
+
+- 页容量选择基于 MyGo `SelectBase`，弹层由 MujicaUI 绘制。

docs/components/063-steps.md

@@ -0,0 +1,59 @@
+# 063 Steps 步骤条
+
+## 用途
+
+显示多步流程的进度：已完成、当前、等待和出错四种状态；横向或纵向排列；每一步是否可点击由调用方决定。
+
+## 最小示例
+
+```go
+mujica.Steps(c, &current, []mujica.Step{
+	{Title: "Account", Clickable: true},
+	{Title: "Profile", Description: "Name and seal"},
+	{Title: "Confirm"},
+}, mujica.StepsOptions{Label: "Sign-up"})
+```
+
+签名：`func Steps(c *ui.Context, current *int, steps []Step, opts StepsOptions) StepsResult`
+
+## 参数
+
+`current`：进行中的步骤下标；之前的步骤视为已完成。等于 `len(steps)` 表示全部完成；超出范围 panic。`steps` 为空时 panic。
+
+`Step`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Title` | `string` | 必填 | 步骤标题；为空时 panic。 |
+| `Description` | `string` | "" | 标题下的说明文字。 |
+| `Error` | `bool` | false | 标为出错，优先于位置推导的状态。 |
+| `Clickable` | `bool` | false | 允许用户点击跳到该步。 |
+
+`StepsOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Vertical` | `bool` | false | 纵向排列，连接线在标记下方。 |
+| `Label` | `string` | "" | 整组的无障碍名称。 |
+
+返回 `StepsResult`，内嵌 `*ui.Element`。
+
+## 状态
+
+- 已完成：Accent 圆形标记内 OnAccent 勾号；之后的连接线为 AccentText。
+- 当前：AccentText 圆环与序号，标题 600 字重。
+- 等待：ControlBorder 圆环与 TextMuted 序号、标题。
+- 出错：Danger 圆环与叉号，标题 Danger 色。
+- 每步的无障碍名称为“第 n 步，共 m 步：标题，状态”，状态不只靠颜色表达。
+
+## 事件
+
+- `Changed()`：本帧用户点击了可点击的步骤，`*current` 已更新。
+
+## 键盘操作
+
+- 可点击的步骤组成一个 Tab 停靠点，方向键在其间移动，Enter 或 Space 跳到该步。不可点击的步骤不获取焦点。
+
+## 限制
+
+- MyGo 没有 step 或 aria-current 角色；步骤以列表项（可点击时为按钮）呈现，状态写入名称。

docs/components/064-sidebar.md

@@ -0,0 +1,71 @@
+# 064 Sidebar 侧边栏
+
+## 用途
+
+应用的源列表导航：分组、嵌套、图标、计数和选中项，分组与嵌套组可展开折叠；紧凑模式只显示图标。基于 MyGo `ui.Sidebar`，保留其键盘、首字母跳转与树形无障碍结构。
+
+## 最小示例
+
+```go
+mujica.Sidebar(c, &selected, []mujica.SidebarSection{
+	{Title: "Mail", Items: []mujica.SidebarItem{
+		{ID: "inbox", Label: "Inbox", Icon: icons.Must("inbox"), Count: 3},
+		{Label: "Folders", Items: []mujica.SidebarItem{{ID: "work", Label: "Work", Icon: icons.Must("folder")}}},
+	}},
+}, mujica.SidebarOptions{})
+```
+
+签名：`func Sidebar(c *ui.Context, selected *string, sections []SidebarSection, opts SidebarOptions) SidebarResult`
+
+## 参数
+
+`selected`：选中项的 ID。
+
+`SidebarSection`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Title` | `string` | 必填 | 分组标题，点击展开折叠；为空时 panic（紧凑模式不显示）。 |
+| `Items` | `[]SidebarItem` | nil | 分组内的项。 |
+
+`SidebarItem`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `ID` | `string` | 叶子项必填 | 选择时写入 `*selected`；叶子项为空时 panic。 |
+| `Label` | `string` | 必填 | 名称；为空时 panic。 |
+| `Icon` | `*ui.SVG` | nil | 名称前图标；紧凑模式下必填。 |
+| `Count` | `int` | 0 | 大于 0 时在右侧显示计数，超过 999 显示 “999+”。 |
+| `Items` | `[]SidebarItem` | nil | 非 nil 时该项成为可展开折叠的嵌套组，子项缩进。 |
+
+`SidebarOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Compact` | `bool` | false | 图标栏：隐藏文字与组标题，组之间以旧金细线分隔，名称作为悬停提示。 |
+| `Width` | `float32` | 0（240，紧凑时 56） | 宽度，DIP。高度填满父容器。 |
+
+返回 `SidebarResult`，内嵌 `*ui.Element`。展开折叠状态由组件保存。
+
+## 状态
+
+- 选中：Selection 背景、左侧 3 DIP AccentText 边线、600 字重，三者同时标记。
+- 悬停：SurfaceHover 背景。
+- 焦点：侧边栏获得焦点时，在选中项上画焦点环。
+- 计数：等宽数字，名称附计数（如 “Inbox (12)”）。
+
+## 事件
+
+- `Changed()`：本帧用户选择了新项。
+
+## 键盘操作
+
+- Tab：进入侧边栏（一个停靠点）。
+- ↑/↓：上一项/下一项；Home / End：首项/末项；输入名称开头字母跳到匹配项。
+- 分组与嵌套组标题用指针点击展开折叠。
+
+## 限制
+
+- 复用 MyGo `ui.SidebarItem`，它用主题 Accent 绘制图标（`ui/sidebar.go:182`）；深色主题 Accent 对比度不足，本组件在构建侧边栏时临时把 MyGo 主题的 Accent 换成 AccentText。
+- MyGo `SidebarItem` 总是追加名称文字（`ui/sidebar.go:212`）；紧凑模式传入空名称，名称改由 `Label` 与提示提供，因此紧凑模式下首字母跳转不可用。
+- 嵌套组用 MyGo `SidebarSection` 实现，组标题本身不能被选中，且只能用指针展开折叠（MyGo 不给标题注册按键）。

docs/components/065-navigation-menu.md

@@ -0,0 +1,61 @@
+# 065 NavigationMenu 导航菜单
+
+## 用途
+
+站点式的顶层导航：直接链接与下拉分组（分组内可再分小节），用应用已有的 `*ui.Router` 标记当前路径并跳转；可选显示 MyGo 的后退、前进按钮。
+
+## 最小示例
+
+```go
+mujica.NavigationMenu(c, router, []mujica.NavigationLink{
+	{Label: "Home", Path: "/"},
+	{Label: "Library", Items: []mujica.NavigationLink{
+		{Label: "Poems", Path: "/library/poems", Description: "Verse of the court"},
+	}},
+}, mujica.NavigationMenuOptions{History: true})
+router.View(c, func(r *ui.Route) { ui.Text(c, r.Path()) })
+```
+
+签名：`func NavigationMenu(c *ui.Context, router *ui.Router, links []NavigationLink, opts NavigationMenuOptions) *ui.Element`
+
+## 参数
+
+`router` 为 nil 或 `links` 为空时 panic。路由状态由应用持有，组件只读 `Path()` 并调用 `Push`。
+
+`NavigationLink`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Label` | `string` | 必填 | 名称；为空时 panic。 |
+| `Path` | `string` | 叶子必填 | 点击后 `router.Push(Path)`；既无 `Path` 也无 `Items` 时 panic。 |
+| `Icon` | `*ui.SVG` | nil | 名称前图标。 |
+| `Description` | `string` | "" | 下拉面板中名称下方的说明。 |
+| `Items` | `[]NavigationLink` | nil | 非 nil 时为分组：顶层显示为下拉按钮，面板内显示为小节标题。 |
+
+`NavigationMenuOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `History` | `bool` | false | 在前面显示后退、前进按钮（MyGo `BackButton` / `ForwardButton`）。 |
+| `Label` | `string` | 内置“导航菜单” | 链接组的无障碍名称。 |
+
+## 状态
+
+- 当前路径：路径等于链接，或位于其下（`/library` 覆盖 `/library/poems`；`/` 只匹配自身）。顶层项以 600 字重与底部 AccentText 线标记；面板中的当前项为 Selection 背景、左侧边线与 600 字重。
+- 悬停或展开：SurfaceHover 背景。焦点环 2 DIP。
+- 历史按钮在历史两端禁用；右键列出可前往的页面（MyGo 行为）。
+
+## 事件
+
+- 无返回事件：跳转直接作用于 `router`，调用方读取 `router.Path()`。
+
+## 键盘操作
+
+- Tab：进入顶层链接组；←/→ 在顶层项之间移动。
+- 在分组上按 ↓、Enter 或 Space 打开面板，焦点在第一个链接；↑/↓ 在面板内移动，Enter 跳转并关闭，Escape 关闭并把焦点还给分组按钮。
+- 历史：Cmd+[ / Cmd+]（macOS），Alt+←/→（其他平台），以及鼠标侧键，由 MyGo 路由处理。
+
+## 限制
+
+- MyGo 历史按钮的提示文字固定为英文 “Back” / “Forward”（`ui/router.go:713`）；本组件覆盖了无障碍名称，但提示仍为英文。
+- 历史按钮的外观来自 MyGo 主题按钮样式（经 `mujica.Use` 映射为 MujicaUI 颜色）。

docs/components/066-menubar.md

@@ -0,0 +1,74 @@
+# 066 Menubar 菜单栏
+
+## 用途
+
+应用窗口内由 MujicaUI 自绘的菜单栏（不是系统菜单）：多级子菜单、勾选项、单选项、分隔线、快捷键提示和完整键盘导航。
+
+## 最小示例
+
+```go
+res := mujica.Menubar(c, []mujica.MenubarMenu{
+	{Label: "File", Items: []mujica.MenubarItem{
+		{ID: "new", Label: "New", Shortcut: mujica.MenubarShortcut{Mods: ui.Cmd, Key: ui.KeyN}},
+		{Label: "Export", Items: []mujica.MenubarItem{{ID: "pdf", Label: "PDF"}}},
+	}},
+	{Label: "View", Items: []mujica.MenubarItem{
+		{ID: "wrap", Label: "Word wrap", Kind: mujica.MenubarCheck, Checked: wrap},
+	}},
+}, mujica.MenubarOptions{})
+if id, ok := res.Chosen(); ok && id == "wrap" {
+	wrap = !wrap
+}
+```
+
+签名：`func Menubar(c *ui.Context, menus []MenubarMenu, opts MenubarOptions) MenubarResult`
+
+## 参数
+
+`menus` 为空或标题为空时 panic。
+
+`MenubarItem`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `ID` | `string` | 必填（子菜单与分隔线除外） | `Chosen` 报告的标识。 |
+| `Label` | `string` | 必填（分隔线除外） | 名称。 |
+| `Kind` | `MenubarItemKind` | `MenubarAction` | `MenubarAction`、`MenubarCheck`、`MenubarRadio`、`MenubarSeparator`。子菜单必须为 `MenubarAction`。 |
+| `Checked` | `bool` | false | 勾选项与单选项的当前值，由调用方持有。 |
+| `Disabled` | `bool` | false | 禁用：不可选择，方向键跳过。 |
+| `Shortcut` | `MenubarShortcut` | 无 | 仅显示的快捷键提示：macOS 显示 ⌘⇧ 等符号，其他平台显示 Ctrl+Shift+。键名无法表示时 panic。 |
+| `Items` | `[]MenubarItem` | nil | 非 nil 时为子菜单。 |
+
+`MenubarOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Label` | `string` | 内置“菜单栏” | 菜单栏的无障碍名称。 |
+
+返回 `MenubarResult`，内嵌菜单栏 `*ui.Element`。
+
+## 状态
+
+- 打开的菜单标题：Selection 背景；高亮项：Selection 背景。
+- 勾选项：AccentText 勾号；单选项：AccentText 菱形标记；名称附“已勾选”。
+- 禁用项：降低不透明度，指针与键盘均跳过。
+- 弹层：6 DIP 圆角、Border 边框；靠近窗口边缘时左移，子菜单放不下时翻到父菜单左侧，过高时上移。
+
+## 事件
+
+- `Chosen() (string, bool)`：本帧被选择的项 ID。选择后菜单关闭；勾选与单选由调用方更新 `Checked`。
+
+## 键盘操作
+
+- Tab：进入菜单栏（一个停靠点）；←/→ 在标题间移动；↓、↑、Enter 或 Space 打开菜单。
+- 菜单中：↑/↓ 移动（跳过分隔线与禁用项并循环），Home / End 到首末项。
+- →：打开子菜单；在普通项上则打开右侧下一个菜单。←：关闭子菜单；在顶层则打开左侧菜单。
+- Enter / Space：选择或打开子菜单。Escape：关闭一级。
+- 指针：点击标题打开；菜单打开时移到其他标题即切换；悬停子菜单项展开；点击外部关闭。
+
+## 限制
+
+- 快捷键只做提示，不注册；用 `c.Shortcut` 处理。
+- MyGo 没有 menu / menuitem 角色（`ui/access.go:25-79`），项以按钮呈现；勾选状态无法通过公开接口写入（`ui/base.go:56` 的 checked 为内部字段），因此写入名称。
+- 指针点击非可聚焦元素会清除焦点（`ui/input.go:238`）；选择后组件把焦点还给对应标题。
+- 菜单打开期间，焦点保持在标题上，高亮项由组件管理（与 MyGo `SelectBase` 相同的方式）。

docs/components/067-toolbar.md

@@ -0,0 +1,67 @@
+# 067 Toolbar 工具栏
+
+## 用途
+
+一行操作按钮：分组、分隔线；宽度不足时，放不下的按钮从末尾起移入溢出菜单。基于 MyGo `ui.Toolbar`，保留其焦点组与溢出行为。
+
+## 最小示例
+
+```go
+mujica.Toolbar(c, mujica.ToolbarOptions{Label: "Format"}, func() {
+	mujica.ToolbarGroup(c, func() {
+		mujica.ToolbarButton(c, "Bold", mujica.ToolbarButtonOptions{Icon: icons.Must("bold")})
+		mujica.ToolbarButton(c, "Italic", mujica.ToolbarButtonOptions{Icon: icons.Must("italic")})
+	})
+	mujica.ToolbarSeparator(c)
+	if mujica.ToolbarButton(c, "Copy", mujica.ToolbarButtonOptions{Icon: icons.Must("copy"), ShowLabel: true}).Clicked() {
+		copySelection()
+	}
+})
+```
+
+签名：
+
+- `func Toolbar(c *ui.Context, opts ToolbarOptions, fn func()) *ui.Element`
+- `func ToolbarButton(c *ui.Context, label string, opts ToolbarButtonOptions) *ui.Element`
+- `func ToolbarGroup(c *ui.Context, fn func()) *ui.Element`
+- `func ToolbarSeparator(c *ui.Context)`
+
+## 参数
+
+`ToolbarOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Label` | `string` | "" | 工具栏的无障碍名称。 |
+
+`ToolbarButton` 的 `label` 必填（为空时 panic）：它是按钮名称、仅图标时的提示文字和溢出菜单中的文字。
+
+`ToolbarButtonOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Icon` | `*ui.SVG` | nil | 16 DIP 图标。 |
+| `ShowLabel` | `bool` | false | 图标旁显示文字；没有图标时总是显示。 |
+| `Disabled` | `bool` | false | 禁用；溢出菜单中同样禁用。 |
+
+## 状态
+
+- 工具栏：Surface 背景、Border 边框、4 DIP 圆角。
+- 按钮：无底色，悬停 SurfaceHover，按下 Selection，焦点环 2 DIP。
+- 分隔线：旧金细竖线，不进入无障碍树。
+- 溢出：末尾显示 “»” 按钮，菜单中按原顺序列出被收起的操作，组之间以分隔线隔开。
+
+## 事件
+
+- `ToolbarButton(...).Clicked()`：点击、Enter / Space，或在溢出菜单中选择。
+
+## 键盘操作
+
+- Tab：进入工具栏（一个停靠点），再按 Tab 离开。
+- ←/→：在操作之间移动（跳过禁用项并循环）；Home / End 到首末。
+- Enter / Space：执行。溢出按钮用 Enter、Space 或 ↓ 打开菜单。
+
+## 限制
+
+- 溢出菜单是 MyGo 打开的系统菜单（`ui/toolbar.go:45`），外观为系统样式，不是 MujicaUI 自绘。
+- 溢出按钮的无障碍名称固定为英文 “More”（`ui/toolbar.go:44`），按钮样式来自 MyGo 主题。

docs/components/068-command-palette.md

@@ -0,0 +1,65 @@
+# 068 CommandPalette 命令面板
+
+## 用途
+
+用快捷键（默认 Cmd+K，非 macOS 为 Ctrl+K）打开的模态命令搜索框：输入过滤、分组显示、无结果提示、方向键选择，执行后关闭。
+
+## 最小示例
+
+```go
+res := mujica.CommandPalette(c, &open, []mujica.Command{
+	{ID: "new", Label: "New document", Group: "File"},
+	{ID: "theme", Label: "Toggle dark mode", Group: "View", Keywords: []string{"night"}},
+}, mujica.CommandPaletteOptions{})
+if id, ok := res.Chosen(); ok {
+	run(id)
+}
+```
+
+签名：`func CommandPalette(c *ui.Context, open *bool, commands []Command, opts CommandPaletteOptions) CommandPaletteResult`
+
+## 参数
+
+`open`：是否显示；快捷键把它设为 true，执行、Escape 或点击遮罩设为 false。调用方也可直接设置。
+
+`Command`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `ID` | `string` | 必填 | `Chosen` 报告的标识；为空或重复时 panic。 |
+| `Label` | `string` | 必填 | 显示名称；为空时 panic。 |
+| `Group` | `string` | "" | 分组标题；分组按首次出现的顺序排列，组内保持原顺序。 |
+| `Keywords` | `[]string` | nil | 额外的搜索词。 |
+| `Icon` | `*ui.SVG` | nil | 名称前图标。 |
+
+`CommandPaletteOptions`
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `OpenMods` | `ui.Modifiers` | 0 | 打开快捷键的修饰键。 |
+| `OpenKey` | `ui.Key` | 0（即 `ui.Cmd`+K） | 打开快捷键；为 0 时忽略 `OpenMods`。 |
+
+返回 `CommandPaletteResult`；关闭时其 `Element` 为 nil。
+
+## 状态
+
+- 打开：遮罩变暗，面板在窗口上部，焦点在搜索框；每次打开都清空搜索。
+- 搜索：不区分大小写，按空格分词，每个词须出现在名称、分组或关键词中。
+- 高亮项：Selection 背景、左侧 AccentText 边线、600 字重；键盘移动时滚入视野。
+- 无结果：显示“没有匹配的命令”，Enter 不执行任何命令。
+- 底部提示栏说明 ↑↓、Enter、Esc。
+
+## 事件
+
+- `Chosen() (string, bool)`：本帧执行的命令 ID（Enter 或点击），同时关闭面板。
+
+## 键盘操作
+
+- Cmd+K / Ctrl+K：打开（窗口级快捷键）。
+- 输入：过滤。↑/↓：移动高亮并循环。Enter：执行并关闭。Escape：关闭不执行，焦点回到打开前的元素。
+- Tab 限制在面板内（MyGo 模态对话框行为）。
+
+## 限制
+
+- MyGo `TextInputBase` 没有占位文字（`ui/editor.go:734`）；为避免与输入法组合文字重叠，说明放在底部提示栏，搜索框以无障碍名称“搜索命令”标识。
+- 搜索是子串匹配，不做模糊匹配或排序打分。

docs/components/081-dialog.md

@@ -0,0 +1,75 @@
+# 081 Dialog 对话框
+
+## 用途
+
+在窗口上方显示模态对话框：标题、说明、内容与操作区。打开时限制焦点并屏蔽背景，关闭后把焦点还给打开它的控件。视觉回归基准组件之一。
+
+## 最小示例
+
+```go
+open := true
+name := "Ophelia"
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.Button(c, "Rename…", mujica.ButtonOptions{}).Clicked() {
+		open = true
+	}
+	mujica.Dialog(c, &open, mujica.DialogOptions{
+		Title:       "Rename the chamber",
+		Description: "The new name shows in every hall.",
+		Decorated:   true,
+		Actions: func() {
+			if mujica.Button(c, "Cancel", mujica.ButtonOptions{Variant: mujica.Secondary}).Clicked() {
+				open = false
+			}
+			if mujica.Button(c, "Rename", mujica.ButtonOptions{}).Clicked() {
+				open = false
+			}
+		},
+	}, func() {
+		ui.TextInput(c, &name)
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func Dialog(c *ui.Context, open *bool, opts DialogOptions, content func()) *ui.Element`，关闭时返回 nil。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Title` | `string` | 必填 | 衬线标题，也是对话框的无障碍名称；为空时 panic。 |
+| `Description` | `string` | `""` | 标题下的说明文字，同时作为无障碍描述。 |
+| `Width` | `float32` | `440` | 面板宽度（DIP），始终不超过窗口宽度减 32。 |
+| `Decorated` | `bool` | `false` | 开启双线边框、四角菱形角饰和标题下的装饰线。 |
+| `Actions` | `func()` | `nil` | 页脚操作区，靠右排列，可换行。 |
+| `KeepOnBackdrop` | `bool` | `false` | 点击遮罩不关闭。 |
+| `KeepOnEscape` | `bool` | `false` | Escape 不关闭。 |
+| `HideClose` | `bool` | `false` | 不显示右上角关闭按钮。 |
+
+`open` 为 false 时不构建任何元素。`content` 可为 nil；内容超出窗口高度时在内容区滚动。
+
+## 状态
+
+- 打开：遮罩渐入，面板 160 ms 淡入并上移 8 DIP；减少动画时直接显示。
+- 关闭按钮：悬停、按下、键盘焦点环（2 DIP，留 2 DIP 间隔）。
+- 装饰：只出现在边缘与标题区，不占焦点，不影响点击区域。
+
+## 事件
+
+- 关闭按钮、遮罩点击、Escape 把 `*open` 设为 false（各自可关闭）。
+- 业务事件由 `Actions` 和 `content` 中的控件自己报告。
+
+## 键盘操作
+
+| 按键 | 行为 |
+| --- | --- |
+| Tab / Shift+Tab | 在对话框内循环，不会离开。 |
+| Escape | 先交给输入法与正在编辑的控件，再关闭最上层浮层；嵌套 Popover 或菜单先关。 |
+| Enter / Space | 触发聚焦的按钮。 |
+
+## 限制
+
+- 关闭后焦点回到打开时的控件；若该控件已不存在，MyGo 不回退到父级（`ui/scope.go:137` restoreFocus 只恢复原控件），焦点为空，再按 Tab 从窗口开头开始。
+- 没有关闭过渡：MyGo 在 `*open` 变为 false 的下一帧即移除浮层元素，`Transition` 的 Exit 需要父元素保留，而浮层根只在有浮层时存在。

docs/components/082-alert-dialog.md

@@ -0,0 +1,65 @@
+# 082 AlertDialog 警示对话框
+
+## 用途
+
+确认危险操作。默认聚焦“取消”，点击遮罩无效，Escape 等同取消；可要求先输入目标名称，未确认目标前 Enter 不会执行。
+
+## 最小示例
+
+```go
+open := true
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.Button(c, "Delete archive", mujica.ButtonOptions{Variant: mujica.Danger}).Clicked() {
+		open = true
+	}
+	r := mujica.AlertDialog(c, &open, mujica.AlertDialogOptions{
+		Title:       "Delete the archive?",
+		Description: "Twelve letters will be destroyed.",
+		ConfirmText: "archive",
+	})
+	if r.Confirmed {
+		fmt.Println("deleted")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func AlertDialog(c *ui.Context, open *bool, opts AlertDialogOptions) AlertDialogResult`。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Title` | `string` | 必填 | 标题与无障碍名称；为空时 panic。 |
+| `Description` | `string` | `""` | 后果说明，同时作为无障碍描述。 |
+| `ConfirmLabel` | `string` | 内置“删除 / Delete” | 危险按钮文字。 |
+| `CancelLabel` | `string` | 内置“取消 / Cancel” | 取消按钮文字。 |
+| `ConfirmText` | `string` | `""` | 非空时显示输入框，输入内容与之完全相同后确认按钮才可用。 |
+
+`AlertDialogResult{Confirmed, Cancelled bool}` 只在发生选择的那一帧为 true，之后对话框关闭。
+
+## 状态
+
+- 确认按钮使用 Danger 变体；`ConfirmText` 未匹配时禁用（MyGo 统一变暗）。
+- 输入框有边框与焦点环；内容保留在对话框打开期间，关闭后清空。
+
+## 事件
+
+- `Confirmed`：点击确认，或在输入框内按 Enter 且目标已匹配。
+- `Cancelled`：点击取消、在取消上按 Enter / Space、或按 Escape。
+- 点击遮罩不产生事件。
+
+## 键盘操作
+
+| 按键 | 行为 |
+| --- | --- |
+| 打开时 | 焦点在“取消”。 |
+| Enter | 触发聚焦的按钮；在输入框中只有目标匹配时确认。 |
+| Escape | 取消并关闭。 |
+| Tab | 在对话框内循环。 |
+
+## 限制
+
+- 取消按钮的焦点由 `AutoFocus` 给出，打开时不显示焦点环（MyGo 只在键盘移动焦点后设置可见焦点，`ui/input.go:868`）；按 Tab 后显示。
+- 不替代系统原生警示框；需要系统样式时用 MyGo 的桌面对话框。

docs/components/083-drawer.md

@@ -0,0 +1,55 @@
+# 083 Drawer 抽屉
+
+## 用途
+
+从窗口四边之一滑出的面板，用于筛选、详情和设置。可选模态或非模态。
+
+## 最小示例
+
+```go
+open := true
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	if mujica.Button(c, "Filters", mujica.ButtonOptions{}).Clicked() {
+		open = true
+	}
+	mujica.Drawer(c, &open, mujica.DrawerOptions{Title: "Filters", Side: mujica.DrawerRight, Size: 320}, func() {
+		ui.Text(c, "Guests are placed by rank.")
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func Drawer(c *ui.Context, open *bool, opts DrawerOptions, content func()) *ui.Element`。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Title` | `string` | 必填 | 标题与无障碍名称；为空时 panic。 |
+| `Side` | `DrawerSide` | `DrawerRight` | `DrawerRight`、`DrawerLeft`、`DrawerTop`、`DrawerBottom`；越界时 panic。 |
+| `Size` | `float32` | 左右 360，上下 280 | 宽度或高度；限制在 160 DIP 与窗口的 90% 之间；负数 panic。 |
+| `NonModal` | `bool` | `false` | 非模态：不加遮罩、不限制焦点，窗口其余部分仍可操作。 |
+| `Actions` | `func()` | `nil` | 页脚操作区。 |
+
+## 状态
+
+- 打开时从所在边滑入并淡入 160 ms；减少动画时直接出现。
+- 面板贴边，只在朝内一侧画 1 DIP 分隔线。
+- 内容超出时在内容区滚动。
+
+## 事件
+
+关闭按钮与 Escape 把 `*open` 设为 false；模态抽屉点击遮罩同样关闭。
+
+## 键盘操作
+
+| 按键 | 行为 |
+| --- | --- |
+| Tab / Shift+Tab | 模态：在抽屉内循环。非模态：按窗口焦点顺序，抽屉内容排在窗口内容之后。 |
+| Escape | 关闭（先交给正在编辑的控件和更上层浮层）。 |
+
+## 限制
+
+- 非模态抽屉不在打开时移动焦点，关闭时也不自动恢复焦点：MyGo 记录与恢复打开者的 `openOverlay` 不公开（`ui/scope.go:123`），也没有读取当前焦点的公开接口。
+- 非模态抽屉的 Escape 是窗口级快捷键，优先级最低；同时打开多个非模态浮层时由先构建的那个响应。

docs/components/084-popover.md

@@ -0,0 +1,54 @@
+# 084 Popover 弹出框
+
+## 用途
+
+在锚点下方显示可交互的面板；空间不足时翻到上方，并保持在窗口内。外部点击与 Escape 关闭。
+
+## 最小示例
+
+```go
+open := true
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	b := mujica.Button(c, "Guests", mujica.ButtonOptions{Variant: mujica.Secondary})
+	if b.Clicked() {
+		open = !open
+	}
+	mujica.Popover(c, b, &open, mujica.PopoverOptions{Title: "Guest list"}, func() {
+		ui.Text(c, "Twelve guests confirmed.")
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func Popover(c *ui.Context, anchor *ui.Element, open *bool, opts PopoverOptions, content func()) *ui.Element`。`anchor` 必须是本帧已构建的元素，nil 时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Title` | `string` | `""` | 面板顶部的衬线标题，同时命名面板。 |
+| `Width` | `float32` | 0 | 固定宽度；0 时随内容，至少与锚点同宽，最多 360。 |
+| `Label` | `string` | `""` | 无标题时的无障碍名称。 |
+
+## 状态
+
+- 6 DIP 圆角、Surface 底色、1 DIP 边框、160 ms 淡入。
+- 面板最高为锚点上下较大一侧的空间，超出时滚动。
+- 锚点首帧尚未布局时面板保持透明，避免闪到窗口左上角。
+
+## 事件
+
+外部点击与 Escape 把 `*open` 设为 false；内容内控件自行报告事件。
+
+## 键盘操作
+
+| 按键 | 行为 |
+| --- | --- |
+| Tab | 从锚点进入弹层，弹层元素紧跟锚点排序。 |
+| Escape | 关闭并把焦点还给锚点。 |
+
+## 限制
+
+- 只支持下方与上方两个位置：位置由 MyGo `PopoverBase` 决定（`ui/widgets.go:689` keepInWindow）。
+- 打开时外部点击只用于关闭，不会传给下方控件：`PopoverBase` 用覆盖整窗的背板接收点击（`ui/base.go:373`）。

docs/components/085-tooltip.md

@@ -0,0 +1,45 @@
+# 085 Tooltip 文字提示
+
+## 用途
+
+指针停留或键盘聚焦一段时间后，在元素旁显示简短说明。提示不含交互内容，不拦截指针，并作为元素的无障碍描述。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	b := mujica.Button(c, "Seal", mujica.ButtonOptions{})
+	mujica.Tooltip(c, b, "Seal the letter with wax", mujica.TooltipOptions{})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func Tooltip(c *ui.Context, anchor *ui.Element, text string, opts TooltipOptions) *ui.Element`，返回 `anchor`。`anchor` 为 nil 时 panic；`text` 为空时什么也不做。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Delay` | `time.Duration` | 500 ms | 悬停或键盘聚焦持续多久后显示；负数 panic。 |
+
+## 状态
+
+- 炭黑底（深色主题为象牙底）、2 DIP 圆角、12+1 DIP 文字，最宽 240 DIP 后换行。
+- 默认在元素下方居中，下方放不下时翻到上方，左右限制在窗口内。
+
+## 事件
+
+无业务事件。`text` 同时写入 `anchor` 的无障碍描述。
+
+## 键盘操作
+
+| 按键 | 行为 |
+| --- | --- |
+| Tab 聚焦 | 键盘焦点停留 `Delay` 后显示。 |
+| Escape | 隐藏，直到指针离开或焦点移走。 |
+
+## 限制
+
+- 只在键盘焦点（可见焦点）时显示，鼠标点击获得的焦点不触发，避免点击后弹出提示。
+- 不使用 MyGo 的 `Element.Tooltip`：它只跟随指针、不响应焦点（`ui/widgets.go:549`）。

docs/components/086-hover-card.md

@@ -0,0 +1,52 @@
+# 086 HoverCard 悬停卡片
+
+## 用途
+
+悬停或聚焦锚点时预览更多信息，例如人物资料。指针可以移入卡片并操作其中的控件，键盘可以 Tab 进入卡片，离开后延迟关闭。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	b := mujica.Button(c, "Lady Sakiko", mujica.ButtonOptions{Variant: mujica.Ghost})
+	mujica.HoverCard(c, b, mujica.HoverCardOptions{}, func() {
+		ui.Text(c, "Keyboardist of the court.")
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func HoverCard(c *ui.Context, anchor *ui.Element, opts HoverCardOptions, content func()) *ui.Element`，返回卡片，未显示时为 nil。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `OpenDelay` | `time.Duration` | 500 ms | 悬停或聚焦多久后打开；负数 panic。 |
+| `CloseDelay` | `time.Duration` | 300 ms | 指针与焦点都离开后多久关闭；负数 panic。 |
+| `Width` | `float32` | 280 | 卡片宽度。 |
+| `Label` | `string` | `""` | 卡片的无障碍名称。 |
+
+## 状态
+
+- 打开、关闭都按延迟进行；减少动画时取消淡入。
+- 指针在锚点或卡片上、或键盘焦点在锚点或卡片内时保持打开。
+- 下方空间不足时翻到上方，左右限制在窗口内。
+
+## 事件
+
+返回值由 nil 变为非 nil 即打开；卡片内控件自行报告事件。
+
+## 键盘操作
+
+| 按键 | 行为 |
+| --- | --- |
+| Tab 聚焦锚点 | `OpenDelay` 后打开。 |
+| Tab | 从锚点进入卡片内的控件，再继续到后面的元素。 |
+| Escape | 立即关闭，焦点回到锚点，直到焦点离开前不再打开。 |
+
+## 限制
+
+- 键盘打开时卡片由 `PopoverBase` 承载，以便焦点顺序紧跟锚点；此时卡片外的点击只用于关闭（`ui/base.go:373`）。指针打开时卡片不拦截窗口其余部分。
+- 指针打开时卡片元素在窗口焦点顺序的末尾。

docs/components/087-dropdown-menu.md

@@ -0,0 +1,75 @@
+# 087 DropdownMenu 下拉菜单
+
+## 用途
+
+按钮触发的应用内菜单，由 MujicaUI 自绘（不是系统菜单）。支持分组、子菜单、勾选项与禁用项；选择后按规则关闭。
+
+## 最小示例
+
+```go
+pinned := false
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.DropdownMenu(c, "Actions", mujica.DropdownMenuOptions{}, func(m *mujica.PopupMenu) {
+		m.Group("Letter", func() {
+			if m.Item("Rename", mujica.PopupMenuItemOptions{}) {
+				fmt.Println("rename")
+			}
+			m.Check("Pinned", &pinned, mujica.PopupMenuItemOptions{KeepOpen: true})
+		})
+		m.Submenu("Move to", mujica.PopupMenuItemOptions{}, func(m *mujica.PopupMenu) {
+			m.Item("Archive", mujica.PopupMenuItemOptions{})
+		})
+		m.Separator()
+		m.Item("Burn", mujica.PopupMenuItemOptions{Disabled: true})
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func DropdownMenu(c *ui.Context, label string, opts DropdownMenuOptions, build func(m *PopupMenu)) *ui.Element`，返回触发按钮。`build` 为 nil、或 `label` 与 `opts.Label` 都为空时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Icon` | `*ui.SVG` | `nil` | 标签前的图标。 |
+| `Disabled` | `bool` | `false` | 禁用触发按钮并关闭已打开的菜单。 |
+| `Label` | `string` | `""` | 仅图标按钮的无障碍名称。 |
+
+`PopupMenu` 方法：
+
+| 方法 | 说明 |
+| --- | --- |
+| `Item(label, opts) bool` | 普通项；本帧被选择时返回 true。 |
+| `Check(label, *bool, opts) bool` | 勾选项，切换 `*bool`；本帧变化时返回 true。 |
+| `Submenu(label, opts, build)` | 子菜单项；`build` 为 nil 时 panic。 |
+| `Group(label, fn)` | 带说明文字的分组，前面有内容时自动加分隔线。 |
+| `Separator()` | 分隔线。 |
+
+`PopupMenuItemOptions`：`Disabled bool`（不可选、不进入方向键序列），`KeepOpen bool`（选择后不关闭菜单）。
+
+## 状态
+
+- 触发按钮：次按钮外观加下拉箭头，打开时保持按下底色。
+- 菜单项：悬停或键盘焦点时显示 Selection 底色和左侧 2 DIP 强调条；勾选项显示勾号；禁用项变暗。
+- 菜单面板最高为可用空间，超出时滚动；子菜单在右侧打开，右侧放不下时翻到左侧，下方放不下时上移。
+
+## 事件
+
+`Item` / `Check` 的返回值；每次选择只报告一次。
+
+## 键盘操作
+
+| 按键 | 行为 |
+| --- | --- |
+| Enter / Space / ↓ | 在触发按钮上打开菜单，焦点在第一项。 |
+| ↑ / ↓ / Home / End | 在当前层移动，跳过禁用项，首尾循环。 |
+| → / Enter | 在子菜单项上打开子菜单并进入。 |
+| ← / Escape | 在子菜单中关闭子菜单，回到父项。 |
+| Escape / Tab | 关闭菜单，焦点回到触发按钮。 |
+
+## 限制
+
+- MyGo 没有 menu / menuitem 无障碍角色（`ui/access.go:22` Role 列表），菜单面板报告为 popup，普通项为 button，勾选项为 checkbox，触发按钮为 menu button。
+- 菜单打开期间外部点击只用于关闭（`ui/base.go:373`）。

docs/components/088-context-menu.md

@@ -0,0 +1,55 @@
+# 088 ContextMenu 右键菜单
+
+## 用途
+
+为一块区域提供应用内右键菜单，由 MujicaUI 自绘。右键在指针处打开，键盘在焦点区域下方打开，并避开窗口边缘。菜单项与 DropdownMenu 相同（`PopupMenu`）。
+
+## 最小示例
+
+```go
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	row := ui.Row(c).Padding(12).Children(func() {
+		ui.Text(c, "Letter to the Countess")
+	})
+	mujica.ContextMenu(c, row, mujica.ContextMenuOptions{}, func(m *mujica.PopupMenu) {
+		if m.Item("Reply", mujica.PopupMenuItemOptions{}) {
+			fmt.Println("reply")
+		}
+		m.Item("Delete", mujica.PopupMenuItemOptions{})
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func ContextMenu(c *ui.Context, target *ui.Element, opts ContextMenuOptions, build func(m *PopupMenu)) *ui.Element`，返回 `target`。`target` 或 `build` 为 nil 时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Disabled` | `bool` | `false` | 不响应右键与菜单键，并关闭已打开的菜单。 |
+
+`PopupMenu` 的方法与选项见 [087 DropdownMenu](087-dropdown-menu.md)。
+
+## 状态
+
+与 DropdownMenu 菜单面板相同。右下角附近打开时，菜单向左、向上翻转，保持在窗口内。
+
+## 事件
+
+`Item` / `Check` 的返回值；每次选择只报告一次。
+
+## 键盘操作
+
+| 按键 | 行为 |
+| --- | --- |
+| Menu 键 / Shift+F10 | 焦点在 `target` 内时，在 `target` 左下方打开，焦点在第一项。 |
+| 菜单内按键 | 同 DropdownMenu。 |
+| Escape | 关闭，焦点回到打开前的控件。 |
+
+## 限制
+
+- `target` 必须是容器：菜单会向它追加一个不可见的定位子元素，文字元素不能有非文字子元素（MyGo 会 panic）。
+- 菜单通过 `target.HandleInput` 接收右键按下，因此会替换调用方在同一元素上设置的 `HandleInput`（MyGo 每个元素只保存一个处理函数，`ui/handler.go:73`）。
+- 不使用 MyGo 的 `Element.ContextMenu`：那是系统菜单，PRD 不允许把它当作哥特样式菜单。

docs/components/089-popconfirm.md

@@ -0,0 +1,59 @@
+# 089 Popconfirm 气泡确认
+
+## 用途
+
+在触发控件旁做轻量确认（归档、移出列表等可撤销操作）。说明与面板关联，确认与取消都可聚焦。高风险操作请用 AlertDialog。
+
+## 最小示例
+
+```go
+open := false
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	b := mujica.Button(c, "Archive", mujica.ButtonOptions{Variant: mujica.Secondary})
+	if b.Clicked() {
+		open = true
+	}
+	if mujica.Popconfirm(c, b, &open, mujica.PopconfirmOptions{Title: "Archive this letter?"}).Confirmed {
+		fmt.Println("archived")
+	}
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func Popconfirm(c *ui.Context, anchor *ui.Element, open *bool, opts PopconfirmOptions) PopconfirmResult`。`anchor` 为 nil 或 `Title` 为空时 panic。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Title` | `string` | 必填 | 问题，也是面板的无障碍名称。 |
+| `Description` | `string` | `""` | 补充说明，作为面板的无障碍描述。 |
+| `ConfirmLabel` | `string` | 内置“确定 / Confirm” | 确认按钮文字。 |
+| `CancelLabel` | `string` | 内置“取消 / Cancel” | 取消按钮文字。 |
+| `Danger` | `bool` | `false` | 确认按钮使用危险变体，图标改为 Danger 色。 |
+
+`PopconfirmResult{Confirmed, Cancelled bool}` 只在发生选择的那一帧为 true。
+
+## 状态
+
+与 Popover 相同的面板；下方放不下时翻到上方。
+
+## 事件
+
+- `Confirmed`：点击确认或在其上按 Enter / Space。
+- `Cancelled`：点击取消、Escape、外部点击。
+
+## 键盘操作
+
+| 按键 | 行为 |
+| --- | --- |
+| 打开时 | 焦点在确认按钮。 |
+| Enter | 触发聚焦的按钮。 |
+| Tab | 在取消与确认间移动，焦点顺序紧跟锚点。 |
+| Escape | 取消并把焦点还给锚点。 |
+
+## 限制
+
+- 非模态：不屏蔽窗口，但外部点击只用于取消，不传给下方控件（`ui/base.go:373`）。
+- 位置只有下方与上方（`ui/widgets.go:689`）。

docs/components/090-overlay.md

@@ -0,0 +1,51 @@
+# 090 Overlay 覆盖层
+
+## 用途
+
+在窗口内显示一层自定义内容：九个位置、可选遮罩、模态或非模态。模态时复用 MyGo `DialogBase` 的焦点限制与背景屏蔽，可与 MyGo 自带的 Select、Popover、菜单嵌套使用。
+
+## 最小示例
+
+```go
+open := true
+view := func(c *ui.Context) {
+	mujica.Use(c, mujica.Settings{})
+	mujica.Overlay(c, &open, mujica.OverlayOptions{Place: mujica.OverlayBottomRight, Label: "Now playing"}, func() {
+		ui.Text(c, "Symbol I: △")
+	})
+}
+ui.Render(view, 400, 300, 1)
+```
+
+签名：`func Overlay(c *ui.Context, open *bool, opts OverlayOptions, content func()) *ui.Element`。
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Place` | `OverlayPlace` | `OverlayCenter` | `OverlayCenter`、`Top`、`Bottom`、`Left`、`Right`、`TopLeft`、`TopRight`、`BottomLeft`、`BottomRight`；越界 panic。 |
+| `Inset` | `float32` | 16 | 面板与窗口边缘的距离。 |
+| `Modal` | `bool` | `false` | 限制焦点、屏蔽背景，点击背景关闭。 |
+| `Dim` | `bool` | `false` | 模态时加暗色遮罩；未开 `Modal` 时 panic。 |
+| `Label` | `string` | `""` | 覆盖层的无障碍名称。 |
+
+## 状态
+
+弹层外观（Surface 底、1 DIP 边框、6 DIP 圆角）与 160 ms 淡入；减少动画时直接显示。
+
+## 事件
+
+Escape 与（模态时）背景点击把 `*open` 设为 false。
+
+## 键盘操作
+
+| 按键 | 行为 |
+| --- | --- |
+| Escape | 关闭；先交给编辑中的控件和更上层浮层。 |
+| Tab | 模态时在覆盖层内循环；非模态时覆盖层元素排在窗口焦点顺序末尾。 |
+
+## 限制
+
+- 非模态覆盖层的 Escape 是窗口级快捷键（MyGo 浮层专用快捷键 `overlayShortcut` 不公开，`ui/scope.go:109`），同时打开多个非模态浮层时由先构建的那个响应。
+- 非模态覆盖层关闭时不自动恢复焦点（`ui/scope.go:123` openOverlay 不公开）。
+- 非模态面板首帧尚未测量尺寸，该帧透明，下一帧定位后淡入。

docs/components/091-alert.md

@@ -0,0 +1,51 @@
+# 091 Alert 提示条
+
+## 用途
+
+在页面内显示一条信息、成功、警告或错误提示，可带标题、一个操作按钮和关闭按钮。严重程度同时由左侧色条、图标和无障碍名称（如“Error”）表达，不只靠颜色。
+
+## 最小示例
+
+```go
+open := true
+r := mujica.Alert(c, &open, "The archive could not be read.", mujica.AlertOptions{
+	Severity: mujica.SeverityError,
+	Title:    "Import failed",
+	Action:   "Retry",
+})
+if r.Action {
+	// retry the import
+}
+```
+
+签名：`func Alert(c *ui.Context, open *bool, message string, opts AlertOptions) AlertResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `open` | `*bool` | `nil` | 非 nil 时显示关闭按钮，关闭后置为 `false`；为 `false` 时不构建任何元素。`nil` 表示不可关闭。 |
+| `message` | `string` | 必填 | 正文；为空时 panic。 |
+| `Severity` | `Severity` | `SeverityInfo` | `SeverityInfo`、`SeveritySuccess`、`SeverityWarning`、`SeverityError`。 |
+| `Title` | `string` | `""` | 正文上方的粗体标题。 |
+| `Action` | `string` | `""` | 操作按钮文字；为空不显示。 |
+
+返回 `AlertResult{Element, Action, Closed}`；关闭状态下 `Element` 为 nil。
+
+## 状态
+
+四种严重程度；操作与关闭按钮有悬停、按下和 2 DIP 焦点环。警告与错误在出现或文字变化时通过 `Context.Announce` 播报一次。
+
+## 事件
+
+- `Action`：操作按钮被点击或经键盘触发。
+- `Closed`：用户关闭；同时 `*open` 变为 `false`。
+
+## 键盘操作
+
+Tab 依次聚焦操作按钮与关闭按钮；Enter 或 Space 触发。
+
+## 限制
+
+- 信息与成功提示不主动播报，避免页面加载时打扰读屏用户。
+- 关闭不带退出动画；需要动画时由调用方在外层加 `Transition`。

docs/components/092-toast.md

@@ -0,0 +1,58 @@
+# 092 Toast 轻提示
+
+## 用途
+
+在窗口右下角短暂显示操作结果，可带一个操作（如撤销）与关闭按钮。每个窗口一条队列：按 ID 去重，同时最多显示 3 条，其余排队。
+
+## 最小示例
+
+```go
+if mujica.Button(c, "Delete note", mujica.ButtonOptions{Variant: mujica.Danger}).Clicked() {
+	mujica.ShowToast(c, mujica.ToastMessage{ID: "note-1", Message: "Note deleted", Action: "Undo"})
+}
+// Last in the view:
+if r := mujica.Toaster(c); r.Action == "note-1" {
+	// restore the note
+}
+```
+
+接口：
+
+- `func ShowToast(c *ui.Context, m ToastMessage)`：加入队列，须在界面线程调用（后台任务经 `Window.Update` 回到界面线程）。
+- `func DismissToast(c *ui.Context, id string)`：关闭显示中或排队中的消息。
+- `func Toaster(c *ui.Context) ToasterResult`：每帧在视图末尾调用一次，绘制消息并报告事件。
+
+## 参数
+
+`ToastMessage`：
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `ID` | `string` | `Message` | 去重键。相同 ID 再次显示时替换内容并重新计时，不新增一条。 |
+| `Severity` | `Severity` | `SeverityInfo` | 图标、色条与颜色。 |
+| `Message` | `string` | 必填 | 文字；为空时 panic。 |
+| `Action` | `string` | `""` | 操作按钮文字。 |
+| `Duration` | `time.Duration` | `ToastDuration`（5 秒） | 显示时长；负数 panic。错误消息在为 0 时一直保留到用户关闭。 |
+
+常量：`ToastDuration = 5 * time.Second`，`ToastVisible = 3`。
+
+## 状态
+
+- 排队消息在显示时才开始计时。
+- 指针悬停或焦点位于消息内时暂停计时，离开后从剩余时间继续。
+- 出现时向读屏播报文字；进出场 160 ms 位移与淡入，减少动画时直接切换。
+
+## 事件
+
+`ToasterResult{Action, Closed}`：本帧被点击操作或被关闭的消息 ID；两者都会移除该消息。到时自动消失不报告。
+
+## 键盘操作
+
+消息从不抢夺焦点，正在输入的文本框保持焦点。Tab 在页面之后到达消息中的按钮；焦点在消息内时 Escape 关闭该消息。
+
+## 复用与限制
+
+MyGo 自带 `c.Toast` / `c.ToastAction`（docs/ui/toast.md），但它按文字去重、没有 ID、不限制条数、无关闭按钮、错误不能常驻、外观不可替换，计时只在悬停时暂停而不在聚焦时暂停。这些都是 PRD §5.5 的要求，因此 MujicaUI 自建队列，只复用 MyGo 的 `Overlay`、`Transition`、`Announce` 与 `After` 定时唤醒。
+
+- 所有消息（不只是含操作的消息）都在悬停或聚焦时暂停，这是 PRD 要求的超集，便于阅读。
+- 位置固定在右下角；切换到未调用 `Toaster` 的视图时消息仍在队列中，回来后继续显示。

docs/components/093-progress.md

@@ -0,0 +1,64 @@
+# 093 Progress 进度
+
+## 用途
+
+显示任务进度（确定或不确定，线形或环形），以及计量值（如磁盘占用）及其阈值。归并 MyGo 的 Progress bar 与 Meter：`Progress` 为进度模式，`Meter` 为计量模式。两者分别基于 `ui.Progress` 与 `ui.Meter` 元素重绘，保留其无障碍角色与数值。
+
+## 最小示例
+
+```go
+mujica.Progress(c, 0.62, mujica.ProgressOptions{Label: "Uploading", ShowValue: true})
+mujica.Progress(c, 0, mujica.ProgressOptions{Shape: mujica.ProgressRing, Indeterminate: true, Label: "Connecting"})
+mujica.Meter(c, 93, mujica.MeterOptions{
+	Max: 100, Label: "Disk", ShowValue: true,
+	Levels: &ui.MeterLevels{Warning: 70, Critical: 90},
+})
+```
+
+签名：
+
+- `func Progress(c *ui.Context, value float64, opts ProgressOptions) *ui.Element`
+- `func Meter(c *ui.Context, value float64, opts MeterOptions) *ui.Element`
+
+## 参数
+
+`ProgressOptions`：
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `value` | `float64` | 必填 | 0 到 1；超出或 NaN 时 panic（不确定模式忽略）。 |
+| `Shape` | `ProgressShape` | `ProgressLinear` | `ProgressLinear` 或 `ProgressRing`。 |
+| `Indeterminate` | `bool` | `false` | 未知长度的进度。 |
+| `Label` | `string` | `""` | 显示在旁边并作为无障碍名称；为空时名称为“Loading”。 |
+| `ShowValue` | `bool` | `false` | 显示百分比。 |
+| `Size` | `float32` | 环形 48、线形填满 | 环形直径或线形宽度；负数 panic。 |
+
+`MeterOptions`：
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `value` | `float64` | 必填 | 须在范围内，否则 panic。 |
+| `Min`, `Max` | `float64` | 0, 1（两者都为 0 时） | 范围；`Max <= Min` panic。 |
+| `Levels` | `*ui.MeterLevels` | `nil` | 阈值：达到 `Warning` 为偏高、达到 `Critical` 为严重；`Critical < Warning` 时低值为坏（如电量）。须在范围内。 |
+| `Label` | `string` | `""` | 名称。 |
+| `ShowValue` | `bool` | `false` | 显示“值 / 最大值”。 |
+| `Width` | `float32` | 填满 | 宽度。 |
+
+## 状态
+
+- 确定进度变化时以 120 ms 过渡，减少动画时直接跳到新值。
+- 不确定进度只在绘制时移动（只重绘、不重建视图）；减少动画时显示静态填充和“In progress”文字。
+- 计量条按级别使用 Success / Warning / Danger 颜色，同时显示“Normal / High / Critical / Low”文字与阈值刻度，并把级别写入无障碍名称。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不可聚焦；读屏读取名称与数值。
+
+## 限制
+
+- 环形直径小于 44 DIP 时百分比显示在旁边，而不是环内。
+- MyGo 不提供自定义无障碍数值的公开接口，因此必须基于 `ui.Progress` / `ui.Meter` 元素绘制。

docs/components/094-spinner.md

@@ -0,0 +1,39 @@
+# 094 Spinner 加载标记
+
+## 用途
+
+表示未知长度的加载：四个菱形绕中心旋转。可调尺寸，可显示说明文字。Button 的加载状态也使用它。标记基于 MyGo `ui.Spinner` 元素重绘，读屏视为不确定进度。
+
+## 最小示例
+
+```go
+mujica.Spinner(c, mujica.SpinnerOptions{Size: 20, Label: "Syncing", ShowLabel: true})
+```
+
+签名：`func Spinner(c *ui.Context, opts SpinnerOptions) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Size` | `float32` | 16 | 标记边长（DIP）。 |
+| `Label` | `string` | 内置“Loading / 加载中” | 无障碍名称；`ShowLabel` 时也显示在旁边。 |
+| `ShowLabel` | `bool` | `false` | 在标记旁显示说明。 |
+| `Color` | `ui.Color` | `AccentText` | 标记颜色。 |
+
+## 状态
+
+- 只在被绘制时请求重绘：不再构建（隐藏或停止加载）或滚出视口后动画立即停止，不留定时器。
+- 减少动画模式下静止显示，保留名称与说明。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不可聚焦。
+
+## 限制
+
+- 每帧重绘，而非 MyGo 自带 spinner 的分步重绘；只在显示时产生开销。

docs/components/095-skeleton.md

@@ -0,0 +1,45 @@
+# 095 Skeleton 骨架屏
+
+## 用途
+
+内容加载前占位，形状为文字行、圆形或矩形。尺寸固定，加载完成后替换为真实内容时不跳动。
+
+## 最小示例
+
+```go
+ui.Row(c).Gap(12).Children(func() {
+	mujica.Skeleton(c, mujica.SkeletonOptions{Shape: mujica.SkeletonCircle})
+	ui.Column(c).Grow(1).Children(func() {
+		mujica.Skeleton(c, mujica.SkeletonOptions{Lines: 2})
+	})
+})
+```
+
+签名：`func Skeleton(c *ui.Context, opts SkeletonOptions) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Shape` | `SkeletonShape` | `SkeletonText` | `SkeletonText`、`SkeletonCircle`、`SkeletonRect`。 |
+| `Width` | `float32` | 填满父级；圆形 40 | 宽度；圆形为直径。 |
+| `Height` | `float32` | 当前密度控件高度 | 矩形高度；文字形状由行数决定（每行 21 DIP）。 |
+| `Lines` | `int` | 1 | 文字行数，多行时最后一行为 60% 宽。 |
+
+负值 panic。
+
+## 状态
+
+明暗缓慢脉动（1.6 秒周期），只重绘不重建视图；减少动画模式使用静态填充。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不可聚焦，不进入无障碍树。
+
+## 限制
+
+- 骨架本身不向读屏报告加载；请在容器上配合 Spinner 或 LoadingOverlay 的说明文字。

docs/components/096-empty-state.md

@@ -0,0 +1,48 @@
+# 096 EmptyState 空状态
+
+## 用途
+
+说明视图为何为空并给出下一步。区分“无数据”（集合本身为空）与“无搜索结果”（筛选没有匹配），两者使用不同的默认图标与文案。
+
+## 最小示例
+
+```go
+r := mujica.EmptyState(c, mujica.EmptyStateOptions{
+	Kind:   mujica.EmptyNoResults,
+	Query:  query,
+	Action: "Clear search",
+})
+if r.Action {
+	query = ""
+}
+```
+
+签名：`func EmptyState(c *ui.Context, opts EmptyStateOptions) EmptyStateResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Kind` | `EmptyKind` | `EmptyNoData` | `EmptyNoData` 或 `EmptyNoResults`。 |
+| `Title` | `string` | 按类型的内置文案 | 衬线标题。 |
+| `Description` | `string` | 按类型的内置文案 | 说明。 |
+| `Query` | `string` | `""` | 仅 `EmptyNoResults`：默认说明写出该关键词。用于 `EmptyNoData` 时 panic。 |
+| `Icon` | `*ui.SVG` | inbox / search | 替换图标。 |
+| `NoIcon` | `bool` | `false` | 不显示图标；与 `Icon` 同时设置时 panic。 |
+| `Action` | `string` | `""` | 次按钮文字。 |
+
+## 状态
+
+静态展示；操作按钮有悬停、按下与焦点状态。
+
+## 事件
+
+`EmptyStateResult.Action`：操作按钮被触发。
+
+## 键盘操作
+
+Tab 聚焦操作按钮；Enter 或 Space 触发。
+
+## 限制
+
+- 只有一个操作；需要多个下一步时使用 Result。

docs/components/097-result.md

@@ -0,0 +1,46 @@
+# 097 Result 结果页
+
+## 用途
+
+任务完成后的整页结果：成功、失败或无权限，附说明与下一步操作。组件只报告选择了哪个操作，不执行跳转。标题与操作之间用旧金色细线与菱形分隔。
+
+## 最小示例
+
+```go
+r := mujica.Result(c, mujica.ResultOptions{
+	Kind:        mujica.ResultForbidden,
+	Description: "You need the Editor role to change billing.",
+	Actions:     []string{"Request access", "Go back"},
+})
+switch r.Action {
+case 0: // send the request
+case 1: // navigate back
+}
+```
+
+签名：`func Result(c *ui.Context, opts ResultOptions) ResultResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `Kind` | `ResultKind` | `ResultSuccess` | `ResultSuccess`、`ResultFailure`、`ResultForbidden`；未知值 panic。 |
+| `Title` | `string` | 按类型的内置文案 | 衬线标题。 |
+| `Description` | `string` | `""` | 说明。 |
+| `Actions` | `[]string` | 无 | 下一步操作；第一个为主按钮，其余为次按钮。 |
+
+## 状态
+
+图标（对勾、叉、盾牌）与标题文字共同表达结果，不只靠颜色。按钮有悬停、按下与焦点状态。
+
+## 事件
+
+`ResultResult.Action`：被触发的操作序号，未触发为 -1。
+
+## 键盘操作
+
+Tab 按顺序聚焦操作按钮；Enter 或 Space 触发。
+
+## 限制
+
+- 不含路由；导航由调用方完成。

docs/components/098-status-indicator.md

@@ -0,0 +1,37 @@
+# 098 StatusIndicator 状态标记
+
+## 用途
+
+以图形加文字标出状态：成功、警告、错误、离线、处理中。每种状态有独立形状（对勾圆、三角、叉圆、断开的 Wi-Fi、旋转菱形），并总是显示文字，不只靠颜色。
+
+## 最小示例
+
+```go
+mujica.StatusIndicator(c, mujica.StatusSuccess, mujica.StatusIndicatorOptions{Label: "API online"})
+mujica.StatusIndicator(c, mujica.StatusOffline, mujica.StatusIndicatorOptions{})
+```
+
+签名：`func StatusIndicator(c *ui.Context, status Status, opts StatusIndicatorOptions) *ui.Element`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `status` | `Status` | `StatusSuccess` | `StatusSuccess`、`StatusWarning`、`StatusError`、`StatusOffline`、`StatusBusy`；未知值 panic。 |
+| `Label` | `string` | 内置词（Healthy、Degraded、Failing、Offline、Working） | 替换显示的文字。 |
+
+## 状态
+
+处理中使用 Spinner，减少动画时静止。整体为 `RoleStatus`，名称为文字。
+
+## 事件
+
+无。
+
+## 键盘操作
+
+不可聚焦。
+
+## 限制
+
+- 无 Badge 式的纯圆点模式；PRD 要求不能只靠颜色。

docs/components/099-notification-center.md

@@ -0,0 +1,51 @@
+# 099 NotificationCenter 通知中心
+
+## 用途
+
+应用内消息列表：未读标记、已读/未读切换、单条清除、全部已读、全部清除和每条消息的操作。消息列表与持久化由调用方持有；组件就地修改调用方的切片，并报告发生了什么，供调用方保存。
+
+## 最小示例
+
+```go
+r := mujica.NotificationCenter(c, &items, mujica.NotificationCenterOptions{})
+if r.Action == "a" {
+	// open the build log
+}
+```
+
+签名：`func NotificationCenter(c *ui.Context, items *[]Notification, opts NotificationCenterOptions) NotificationCenterResult`
+
+## 参数
+
+`Notification`：
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `ID` | `string` | 必填 | 列表内唯一；为空或重复时 panic。 |
+| `Title` | `string` | `""` | 标题，未读时加粗。 |
+| `Body` | `string` | `""` | 正文。 |
+| `Time` | `string` | `""` | 按原样显示的时间，如“5 min ago”。 |
+| `Read` | `bool` | `false` | 是否已读。 |
+| `Action` | `string` | `""` | 操作按钮文字。 |
+
+`NotificationCenterOptions.Title`：面板标题，默认“Notifications / 通知”。`items` 为 nil 时 panic。
+
+## 状态
+
+- 未读：左侧酒红菱形、粗体标题、无障碍名称前缀“Unread”。
+- 行悬停加浅底；按钮有悬停、按下与焦点状态；无未读或无消息时头部按钮禁用。
+- 空列表显示 EmptyState。
+- 面板标题下为旧金细线。列表超出容器高度时滚动。
+
+## 事件
+
+`NotificationCenterResult`：`Action`、`Toggled`（已读状态切换）、`Opened`（点击正文后标为已读）、`Removed` 为对应 ID；`MarkedAllRead`、`ClearedAll` 为布尔值。
+
+## 键盘操作
+
+列表是一个 Tab 停靠点；方向键在各条消息及其按钮之间移动，Home/End 到首尾。焦点在消息正文上时 Enter 或 Space 标为已读；Delete 或 Backspace 清除当前消息。
+
+## 限制
+
+- 不分页，也不虚拟化；面向几十到几百条的应用内消息。
+- 时间文字由调用方格式化。

docs/components/100-loading-overlay.md

@@ -0,0 +1,48 @@
+# 100 LoadingOverlay 加载遮罩
+
+## 用途
+
+在一个容器范围内显示加载遮罩：被覆盖的内容不接收指针、按键和焦点，防止重复操作；窗口其余部分照常可用。显示说明文字与可选取消操作。
+
+## 最小示例
+
+```go
+r := mujica.LoadingOverlay(c, loading, mujica.LoadingOverlayOptions{Cancel: "Cancel"}, func() {
+	ui.Text(c, "Quarterly report")
+	mujica.Button(c, "Export", mujica.ButtonOptions{})
+})
+if r.Canceled {
+	loading = false
+}
+```
+
+签名：`func LoadingOverlay(c *ui.Context, loading bool, opts LoadingOverlayOptions, content func()) LoadingOverlayResult`
+
+## 参数
+
+| 字段 | 类型 | 默认值 | 含义 |
+| --- | --- | --- | --- |
+| `loading` | `bool` | 必填 | 是否覆盖。 |
+| `content` | `func()` | 必填 | 构建被覆盖的内容；nil 时 panic。 |
+| `Label` | `string` | 内置“Loading… / 正在加载…” | 说明文字。 |
+| `Cancel` | `string` | `""` | 取消按钮文字；为空时不显示。 |
+
+返回 `LoadingOverlayResult{Element, Canceled}`。`Element` 即遮罩所覆盖的范围，可在其上设置宽高。
+
+## 状态
+
+- 加载时内容经 MyGo `Disabled` 阻止输入（MyGo 统一减淡），上方为半透明背景与居中面板。
+- 开始加载时播报说明；焦点原在内容内时移到取消按钮（无取消时移到可聚焦的说明面板），焦点不会离开该区域。
+- 遮罩淡入淡出，减少动画时直接切换。
+
+## 事件
+
+`Canceled`：点击取消，或焦点在面板内时按 Escape。
+
+## 键盘操作
+
+Tab 到达取消按钮；Enter、Space 或 Escape 取消。被覆盖的控件不进入 Tab 序列。
+
+## 限制
+
+- 只遮盖容器自身范围；整窗阻塞请使用模态对话框。