Inputs: components 021-030

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 清空。