iter(g301): 新增拖拽排序列表 sortableList

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T16:25:36.184Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T16:28:37.124Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -2495,6 +2495,34 @@ noticeBar({ text: '系统将于今晚 23:00 维护 10 分钟', scroll: true })
 
 现场演示：apps/docs/demo.html#sec-notice
 
+### sortableList — 拖拽排序列表 SortableList
+
+参数：
+
+- items（必填）：string[] —— 全部条目文案；文案即排序键，要求唯一（重名会让顺序回读撞车）
+- value：Signal<string[]> —— 受控顺序信号；传了则内部改动写回，外部改动即重排（拖拽中跳过）
+- onChange（回调）：(next: string[]) => void —— 顺序变化回调，拖放落定 / 键盘搬位 / move 调用后各触发一次
+- disabled（默认 false）：boolean | Signal<boolean> —— 禁用拖拽与键盘搬位；缺省 false
+- emptyText：string —— 无条目占位文案；缺省「暂无可排序项」
+
+示例：
+
+```
+const sort = sortableList({ items: ['需求评审', '接口联调', '灰度发布'], onChange: (next) => console.log(next) });
+container.append(sort.el);
+```
+
+手把手：
+
+1. items 传全部条目文案、顺序即当前顺序：文案同时是排序键，所以必须唯一（重名会分不清谁被搬动）
+2. 鼠标 / 触摸按住任意一行拖动，指针越过邻行中线就换位；松手后写回 value 信号并触发 onChange，拖拽期间不重排避免手势中断
+3. 键盘等价：Tab 聚焦某行后按 Alt+↑ / Alt+↓ 上下搬一格、Alt+Home / Alt+End 搬到首尾（裸 ↑↓ 留给页面滚动）
+4. 被拖的行以虚线边框 + 淡色虚影标示，落点由指针位置决定，不会出现「拖了三格只动一格」的错觉
+5. 外部要按代码调整顺序用句柄 move(from, to)，下标越界或禁用时静默忽略；order() 以 DOM 为唯一真相回读当前顺序
+6. 什么时候别用：条目超过一屏（拖到边缘不会自动滚动，改用筛选或上下按钮）、需要跨列表搬运（用两个实例并自己管状态）
+
+现场演示：apps/docs/demo.html#sec-sortable
+
 API 速览：
 
 - button(props)：按钮，variant 三档视觉强度，disabled / loading 支持布尔或信号动态同步（loading 转圈并禁点），onClick 点击回调
@@ -2586,6 +2614,7 @@ API 速览：
 - heatmap(props)：日历热力图，按周列 × 星期行铺格子、四档浓度表示当天数量，悬停看明细
 - progressRing(props)：环形进度，SVG 双圆靠 dasharray 画弧 + 中心百分比，value 可传信号自动重绘
 - noticeBar(props)：单行通知条，语义色 + 左侧符号 + 可选跑马灯与关闭，适合页顶常驻播报
+- sortableList(props)：拖拽排序列表，整行可拖 + Alt+↑↓ 键盘搬位，返回 { el, move, order } 句柄
 
 一行用法：