iter(g329): 新增 editable 行内编辑

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T17:55:42.939Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T17:59:51.593Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -2563,6 +2563,34 @@ masonry({ minColumnWidth: 220, items: shots.map((s) => card({ title: s.title },
 
 现场演示：apps/docs/demo.html#sec-masonry
 
+### editable — 行内编辑 Editable
+
+参数：
+
+- value（必填）：Signal<string> —— 展示值，双向绑定：只有提交才写回，Esc 取消绝不落值
+- placeholder（默认 '点击填写'）：string —— 空值时的占位文案，颜色走辅助文字档
+- label（默认 '编辑'）：string —— 读屏用的字段名，作静止态按钮 aria-label 的前缀（如「标题：季度目标」）
+- multiline：boolean —— 多行模式（textarea）：Enter 换行，Ctrl / Cmd + Enter 才提交；缺省单行
+- disabled：boolean | Signal<boolean> —— 禁用只读，布尔与信号双口径；点了也不进编辑态
+- validate（回调）：(v: string) => string | null —— 提交校验：返回文案即拒绝提交、保持编辑态并标红（aria-invalid + role=alert），返回 null 表示通过
+- onCommit（回调）：(v: string) => void —— 提交回调，值已写回信号之后触发；取消不触发
+
+示例：
+
+```
+const title = signal('季度目标'); editable({ value: title, label: '标题', validate: (v) => (v ? null : '标题不能为空'), onCommit: (v) => toast.success('已保存：' + v) })
+```
+
+手把手：
+
+1. 传一个 Signal<string> 作唯一数据源：组件只在提交时写回，取消路径一个字都不改，「改了没保存」的中间态不会污染业务状态
+2. 点文字进编辑态：Enter 提交、Esc 取消、点别处（失焦）提交；多行模式要 Ctrl / Cmd + Enter 才提交，Enter 留给换行——否则多行里连换行都写不了
+3. validate 返回文案时保留编辑态并标红：控件带 aria-invalid、下方 role=alert 出文案，与 form 的出错口径一致，用户改对再提交即可
+4. disabled 接受布尔或信号：禁用时静止态是灰字、点了不进编辑，适合权限只读的场景（要完全不给「可改」暗示就直接渲染文字）
+5. 什么时候别用：长表单（用 form + textField，editable 没有 label 排版与必填标记）、需要撤销栈的富文本，以及值会被频繁外部改写的地方（编辑中不跟随外部更新，是有意的取舍）
+
+现场演示：apps/docs/demo.html#sec-editable
+
 API 速览：
 
 - button(props)：按钮，variant 三档视觉强度，disabled / loading 支持布尔或信号动态同步（loading 转圈并禁点），onClick 点击回调
@@ -2656,6 +2684,7 @@ API 速览：
 - noticeBar(props)：单行通知条，语义色 + 左侧符号 + 可选跑马灯与关闭，适合页顶常驻播报
 - sortableList(props)：拖拽排序列表，整行可拖 + Alt+↑↓ 键盘搬位，返回 { el, move, order } 句柄
 - masonry(props)：瀑布流多列布局，列宽自适应或固定列数，卡片不被拆到两列
+- editable(props)：行内编辑，静止态是文字、点一下就地变输入框，Enter 提交 / Esc 取消 / 失焦提交
 
 一行用法：