Merge branch 'worktree-agent-a3c9c595e531146d2'

docs/components/041-form.md

@@ -29,7 +29,7 @@ ui.Render(view, 400, 300, 1)
 
 | 字段 | 类型 | 默认值 | 含义 |
 | --- | --- | --- | --- |
-| `FormOptions.Horizontal` | `bool` | false | 标签放在控件左侧一列，右对齐（MyGo `ui.Form` 布局）。 |
+| `FormOptions.Horizontal` | `bool` | false | 标签放在控件左侧一列，右对齐。 |
 | `FormOptions.SubmitLabel` | `string` | 内置“Submit/提交” | 提交按钮文字。 |
 | `FormOptions.ResetLabel` | `string` | 内置“Reset/重置” | 重置按钮文字。 |
 | `FormItemOptions[T].Label` | `string` | 必填 | 字段标签；空值 panic。 |
@@ -56,4 +56,4 @@ Tab / Shift+Tab 在字段间移动，离开字段即校验。提交失败后焦
 - 控件由调用方构建，`FormItem` 的 control 回调必须返回可获取焦点的元素，用于错误定位。
 - 校验在失焦与提交时触发；已触碰字段在值变化时重新同步校验，异步校验只在下一次失焦或提交时重跑。
 - 异步结果以版本号对齐：值变化后旧版本的 `Resolve` 返回 false 并被丢弃。`FormState` 的方法只能在界面线程调用，后台任务需经 `Window.Update` 回到界面线程。
-- 必填标记以“ *”附在标签文字后，屏幕阅读器会一起读出；MyGo 的 Field 标签不支持富文本，无法单独着色。
+- 必填标记“*”只作视觉显示，辅助技术通过说明“必填”获知。

docs/components/042-form-field.md

@@ -4,7 +4,7 @@
 
 ## 用途
 
-为单个控件提供标签、必填标记、说明与错误文字。标签通过 MyGo `ui.Field` 关联控件：屏幕阅读器以标签命名控件，并读出说明与错误；点击标签聚焦控件。
+为单个控件提供标签、必填标记、说明与错误文字。标签、说明与错误显式关联到 control 返回的元素：屏幕阅读器以标签命名该元素并读出说明、必填与错误；点击标签聚焦该元素。
 
 ## 最小示例
 
@@ -12,8 +12,8 @@
 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{})
+	mujica.FormField(c, "Email", mujica.FormFieldOptions{Required: true, Description: "For receipts."}, func() *ui.Element {
+		return mujica.InputGroup(c, &email, mujica.InputGroupOptions{}).Input
 	})
 }
 ui.Render(view, 400, 300, 1)
@@ -24,11 +24,11 @@ ui.Render(view, 400, 300, 1)
 | 字段 | 类型 | 默认值 | 含义 |
 | --- | --- | --- | --- |
 | `label` | `string` | 必填 | 标签文字；空值 panic。 |
-| `FormFieldOptions.Required` | `bool` | false | 在标签后加“ *”。 |
+| `FormFieldOptions.Required` | `bool` | false | 在标签后显示危险色“*”，并向辅助技术说明“必填”。 |
 | `FormFieldOptions.Description` | `string` | "" | 控件下方的说明。 |
 | `FormFieldOptions.Error` | `string` | "" | 控件下方的错误，并把控件标记为无效。 |
 | `FormFieldOptions.Horizontal` | `bool` | false | 标签在左、控件在右。 |
-| `control` | `func()` | 必填 | 构建控件；其中第一个可获取焦点的元素即被关联的控件。 |
+| `control` | `func() *ui.Element` | 必填 | 构建控件并返回要关联的可聚焦元素（如 `InputGroupParts.Input`）；返回 nil 时 panic。 |
 
 ## 状态
 
@@ -44,6 +44,6 @@ Tab 直接到达控件；点击标签聚焦控件，或切换复选框、开关
 
 ## 限制
 
-- 标签、说明与错误文字由 MyGo `ui.Field` 绘制，使用主题颜色（文字、TextMuted、Danger）；字号与间距跟随 MyGo。
-- 错误只把边框染红的效果对 MyGo 自带输入框生效；MujicaUI 的 InputGroup 等需同时传入 `Invalid: true`。
-- 左右布局时多个字段需放在同一个 `ui.Form` 或 MujicaUI `Form(Horizontal)` 中才能对齐标签宽度；单独使用时只按自身标签宽度排列。
+- control 返回的元素的 Label 会被字段标签覆盖。
+- Error 只把元素标记为无效；InputGroup 等的红色边框需同时传入 `Invalid: true`。
+- 左右布局时多个字段需放在 MujicaUI `Form(Horizontal)` 中才能对齐标签宽度；单独使用时只按自身标签宽度排列。