docs: clarify shell input window and host widget lifecycles

src/shell/system_ui/widgets.rs

@@ -1,6 +1,9 @@
 //! 用统一主题绘制宿主管理控件，并同步注册交互目标。
 //! 每个控件的图形、角色、启用状态和 action 一起登记，绘制几何与命中几何保持一致。
 //!
+//! sidebar 和 developer_tools 的 Painter 为每帧创建 Ui，消费其显示列表与 targets，再由外层 Interaction 处理输入。
+//! 这里的 Button 是宿主绘制描述，不是 Endor 的托管 Button；register 只登记 Action，不调用业务回调或立即执行动作。
+//! 主题与 Interaction 是本轮输入快照；控件重绘不会自行改变焦点、按下捕获或滚动偏移，跨帧状态由外层事件处理维护。
 use super::{
     Axis, Interaction, Role, Target, VisualState, WidgetId,
     theme::{self, Theme},
@@ -34,16 +37,19 @@ impl<'a> Button<'a> {
     }
     /// 按 builder 风格设置选中状态，返回描述供链式调用。
     pub fn selected(mut self, value: bool) -> Self {
+        // 侧栏/工具构建链传入本轮选择结果，只改这个短期描述；Ui::button 稍后合成视觉状态，不在这里切换页面。
         self.selected = value;
         self
     }
     /// 设置启用状态，影响外观和目标的可激活资格。
     pub fn enabled(mut self, value: bool) -> Self {
+        // 调用方按业务资格选择是否启用，后面登记到 Target.enabled；不删除动作身份，便于跨帧 reconcile 清理旧捕获。
         self.enabled = value;
         self
     }
     /// 设置控件语义角色，影响焦点资格、光标及 Tab 底线等外观。
     pub fn role(mut self, value: Role) -> Self {
+        // Painter 可为同一按钮原语选择 Tab/Toggle 等角色，后续登记与绘制共用这一描述，不另建一份命中控件。
         self.role = value;
         self
     }
@@ -210,6 +216,7 @@ impl<A: Hash> Ui<A> {
     /// 登记文本输入角色并绘制背景和焦点/悬停描边，不负责实际文本与光标。
     // Network Filter 和 Settings 自定义颜色框使用，仅负责框的目标/外观，实际文字与编辑缓冲由工具状态维护。
     pub fn text_field(&mut self, rect: Rect, action: A, focused: bool) {
+        // Action 的稳定哈希同时关联本帧文本框目标和视觉状态；focused 还允许外层真实编辑焦点提供强调外观。
         let s = self.register(
             WidgetId::new(&action),
             rect,
@@ -250,6 +257,7 @@ impl<A: Hash> Ui<A> {
     // 行背景可绘制完整行，但 hit 可裁到可见部分；不要把裁剪区外的行注册成可点击区域。
     // Painter 为请求、AST 等有动作的显示行调用，paint 可是完整行，hit 只允许可见片段。
     pub fn row(&mut self, paint: Rect, hit: Rect, action: A, selected: bool) {
+        // 目标登记使用裁剪后的 hit，背景使用 paint；源行可以部分可见，不能用完整 paint 扩大鼠标可点击区域。
         let s = self.register(
             WidgetId::new(&action),
             hit,
@@ -263,6 +271,7 @@ impl<A: Hash> Ui<A> {
     /// 登记色块目标，绘制按压变暗、外圈及选中勾号。
     // Settings 调色板调用，颜色来自候选色，selected 来自当前强调色比较；点击只登记主题 Action。
     pub fn swatch(&mut self, rect: Rect, action: A, color: Color, selected: bool) {
+        // 色块 Action 由 Settings 消费，控件只登记/画色；selected 是传入比较结果，不在绘制时改当前主题。
         let s = self.register(
             WidgetId::new(&action),
             rect,
@@ -334,6 +343,7 @@ impl<A: Hash> Ui<A> {
     /// 登记滚动手柄目标并绘制其状态颜色，偏移和拖动倍率由外部维护。
     // Painter 在内容裁剪弹出后调用，只有手柄几何和轴进入 Ui，内容偏移及倍率仍由外层状态管理。
     pub fn scrollbar(&mut self, rect: Rect, id: WidgetId, axis: Axis) {
+        // 无点击 Action，外层用 Role::Scrollbar 和显式 WidgetId 选择拖动状态；Ui 不拥有内容长度或偏移计算。
         let mut s = self.register(id, rect, Role::Scrollbar(axis), None, false, true);
         // 拖动捕获时即使指针移到手柄外仍保持强调色，不能套用普通按钮拖出后取消按下外观的规则。
         s.pressed |= self.interaction.captured(id);