Forms: components 041-050

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 到达全选框、搜索框与移动按钮。
+
+## 限制
+
+- 条目逐项创建，适合数百条以内；大数据量请使用虚拟化列表组合。
+- 全选只作用于当前搜索结果中的可用条目。