Overlays: components 081-090

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 不公开）。
+- 非模态面板首帧尚未测量尺寸，该帧透明，下一帧定位后淡入。