Merge branch 'worktree-agent-a085d9a07ef787c18'

docs/components/021-button.md

@@ -21,7 +21,7 @@ if mujica.Button(c, "Save", mujica.ButtonOptions{Icon: icons.Must("check")}).Cli
 | `label` | `string` | 必填（仅图标时可为空） | 按钮文字；为空时必须提供 `Label`，否则 panic。 |
 | `Variant` | `ButtonVariant` | `Primary` | `Primary`、`Secondary`、`Outline`、`Ghost`、`Danger`。 |
 | `Icon` | `*ui.SVG` | `nil` | 文字前的 16 DIP 图标。 |
-| `Loading` | `bool` | `false` | 有图标时加载标记占用图标位置；纯文字时标记居中覆盖在隐藏的文字上，宽度不变；阻止点击。 |
+| `Loading` | `bool` | `false` | 加载标记出现在前置 16 DIP 图标位置，文字保持可见；有图标时替换图标，纯文字时从左右内边距中让出该位置，宽度不变；阻止点击。 |
 | `Disabled` | `bool` | `false` | 不可点击、不进入 Tab 序列。 |
 | `Label` | `string` | `""` | 无障碍名称；`label` 为空时必填。 |
 

docs/components/024-text-input.md

@@ -32,7 +32,7 @@ if r.Submitted() {
 
 ## 状态
 
-默认（Surface 底、ControlBorder 边）、悬停（边框加深）、聚焦（边框 Focus 色；键盘聚焦另加焦点环）、只读（Background 底、Border 边）、错误、禁用。聚焦时被禁用会放弃焦点，已排队的按键不再修改值、不触发事件。颜色变化 120 毫秒过渡，减少动画时直接切换。
+默认（Surface 底、ControlBorder 边）、悬停（边框加深）、聚焦（边框 Focus 色；键盘聚焦另加焦点环）、只读（Background 底、Border 边）、错误、禁用。禁用来自自身或任一祖先容器；聚焦时被禁用会放弃焦点，已排队的按键不再修改值、不触发事件。颜色变化 120 毫秒过渡，减少动画时直接切换。
 
 ## 事件
 
@@ -41,9 +41,10 @@ if r.Submitted() {
 
 ## 键盘操作
 
-Tab 聚焦（全选内容）；Enter 提交；Escape 清空（仅 `Clearable` 且有内容时，否则交给外层）；Cmd/Ctrl+Z、Shift+Cmd+Z 撤销重做；Cmd/Ctrl+A/C/X/V；输入法组合期间不提交。
+Tab 聚焦（全选内容）；Enter 提交；Escape 清空（仅 `Clearable` 且有内容时，否则交给外层）；Cmd/Ctrl+Z、Shift+Cmd+Z 撤销重做；Cmd/Ctrl+A/C/X/V；组合中的文本不会写入值。
 
 ## 限制
 
+- 输入法组合期间无法阻止 Enter 提交：MyGo 不公开组合状态，组合文本存在未导出的 `editor.compose`（`ui/editor.go:73`），带编辑器的元素收不到 `InputCompose` 事件（`ui/input.go:689`）。公开接口也无法间接得知：`Element.TextCaret`（`ui/handler.go:82`）只是自绘控件声明输入位置的设置方法，`Tester.TextCaret` 返回的 `Active`（`ui/headless.go:370-373`）只表示可编辑元素持有键盘，不表示正在组合。各平台输入法在组合时通常自己消费 Enter。
 - MyGo 没有公开的只读输入接口（只读模式仅用于 `Text.Selectable`，`editor.go:77`）。`ReadOnly` 通过让编辑器编辑一个副本并在同帧还原实现，撤销栈里可能出现被还原的步骤。
 - 清空按钮不进入 Tab 序列（与 MyGo SearchField 相同），键盘用 Escape 清空。

docs/components/025-text-area.md

@@ -45,5 +45,5 @@ if r.Submitted() {
 ## 限制
 
 - `MaxLength` 只提示，不截断输入，以免打断输入法组合与粘贴。
-- 输入法组合期间无法阻止提交快捷键：MyGo 不公开组合状态，组合文本存在未导出的 `editor.compose`（`ui/editor.go:73`），带编辑器的元素收不到 `InputCompose` 事件（`ui/input.go:689`）。各平台输入法在组合时通常自己消费 Enter；只有未被输入法消费的按键会触发提交。
+- 输入法组合期间无法阻止提交快捷键：MyGo 不公开组合状态，组合文本存在未导出的 `editor.compose`（`ui/editor.go:73`），带编辑器的元素收不到 `InputCompose` 事件（`ui/input.go:689`）。各平台输入法在组合时通常自己消费 Enter；只有未被输入法消费的按键会触发提交。公开接口也无法间接得知：`Element.TextCaret`（`ui/handler.go:82`）只是自绘控件声明输入位置的设置方法，`Tester.TextCaret` 返回的 `Active`（`ui/headless.go:370-373`）只表示可编辑元素持有键盘，不表示正在组合。
 - 只读实现方式同 TextInput。

docs/components/026-number-input.md

@@ -2,7 +2,7 @@
 
 ## 用途
 
-输入与步进数值，支持范围、步长、精度与空值。合并 MyGo 的 Number input（输入模式）与 Stepper（`StepperOnly` 仅步进模式）。
+输入与步进数值，支持范围、步长、精度与空值。合并 MyGo 的 Number input（输入模式）与 Stepper（`StepperOnly` 仅步进模式）；两种模式的步进计算都由组件完成。
 
 ## 最小示例
 
@@ -26,7 +26,7 @@ if mujica.NumberInput(c, &copies, mujica.NumberInputOptions{Min: 1, Max: 99, Lab
 | `StepperOnly` | `bool` | `false` | 只显示数值与上下箭头，不可输入；必须给出 `Min < Max`，且不能与 `AllowEmpty` 同用。 |
 | `Placeholder` | `string` | `""` | 空值时的占位。 |
 | `Label` | `string` | `""` | 无障碍名称。 |
-| `Disabled` | `bool` | `false` | 禁用。 |
+| `Disabled` | `bool` | `false` | 禁用；任一祖先容器禁用时同样生效。 |
 | `Error` | `string` | `""` | 调用方给出的错误。 |
 
 ## 状态
@@ -39,11 +39,13 @@ if mujica.NumberInput(c, &copies, mujica.NumberInputOptions{Min: 1, Max: 99, Lab
 
 ## 键盘操作
 
-输入模式：Up/Down 按步长增减。仅步进模式：Up/Right 增加、Down/Left 减少、Home 到最小、End 到最大；按住箭头持续步进。
+步进沿以 `Min`（无界时为 0）为起点、`Step` 为间隔的网格移动，结果按精度取整，并停在范围内（范围先向内取到精度上，如 `Max` 0.29999999、步长 0.1 时最大值为 0.2）。不在网格上的值先吸附到相邻网格点。
+
+输入模式：Up/Down 按步长增减。仅步进模式：Up/Right 增加、Down/Left 减少、Home 到 `Min`、End 到 `Max`（如 [0, 10] 步长 3 时 End 为 10，再 Down 为 9）。
 
 ## 限制
 
 - 输入模式下的加减按钮不进入 Tab 序列，键盘用 Up/Down。
-- 仅步进模式复用 MyGo `ui.Stepper`，箭头高度来自主题间距，不随密度的控件高度变化。
-- MyGo `ui.Stepper` 的箭头不检查禁用（`indicators.go:216`），禁用时组件向它传入副本，保证值不被修改。
-- MyGo 的步进器吸附依赖有限边界（`widgets.go` 中 `snap`），所以仅步进模式要求有界。
+- 仅步进模式不使用 MyGo `ui.Stepper`：它的箭头不检查禁用（`ui/indicators.go:216`），吸附固定按 9 位小数取整（`ui/widgets.go` 中 `snap`），步长 1e-10 时无法前进。组件自绘箭头并自行计算；按住箭头不会连续步进，需重复点击或使用方向键。
+- 仅步进模式要求有界，以便 Home/End 有目标值。
+- 仅步进模式的值通过无障碍描述朗读，MyGo 未公开为自定义元素设置数值范围的接口。

docs/components/028-search-input.md

@@ -48,5 +48,5 @@ if r.Moved() {
 ## 限制
 
 - MyGo 单行编辑器把 Shift+Enter 当作普通提交且不公开修饰键（`editor.go:489`，`submitMods` 未导出），组件用 `HandleInput` 先截获 Shift+Enter。
-- 输入法组合期间无法阻止提交与匹配跳转：MyGo 不公开组合状态，组合文本存在未导出的 `editor.compose`（`ui/editor.go:73`），带编辑器的元素收不到 `InputCompose` 事件（`ui/input.go:689`）。各平台输入法在组合时通常自己消费 Enter；只有未被输入法消费的按键会触发提交或跳转。
+- 输入法组合期间无法阻止提交与匹配跳转：MyGo 不公开组合状态，组合文本存在未导出的 `editor.compose`（`ui/editor.go:73`），带编辑器的元素收不到 `InputCompose` 事件（`ui/input.go:689`）。各平台输入法在组合时通常自己消费 Enter；只有未被输入法消费的按键会触发提交或跳转。公开接口也无法间接得知：`Element.TextCaret`（`ui/handler.go:82`）只是自绘控件声明输入位置的设置方法，`Tester.TextCaret` 返回的 `Active`（`ui/headless.go:370-373`）只表示可编辑元素持有键盘，不表示正在组合。
 - 没有“完成/关闭”按钮；是否显示查找栏由调用方决定。

docs/components/030-radio-group.md

@@ -49,6 +49,6 @@ Tab 进入组并落在已选项；Up/Down/Left/Right 移动并直接选择，循
 
 ## 限制
 
-- 每个选项以 `Value` 为键，选项重新排序后焦点仍跟随原来的值。
+- 每个选项按 `Value` 相等性取得稳定键（首次出现的序号），选项重新排序后焦点仍跟随原来的值；组件记住见过的值，长期不断变化的选项集合会让这份记录增长。
 
 - 方向键对横向与纵向组都同时响应上下左右（MyGo `RadioGroup` 固定使用 `Horizontal|Vertical`）。