Navigation: components 059-068

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`）；为避免与输入法组合文字重叠，说明放在底部提示栏，搜索框以无障碍名称“搜索命令”标识。
+- 搜索是子串匹配，不做模糊匹配或排序打分。