iter(g53): 新增 tour 引导漫游组件

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T04:15:46.909Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T04:17:05.094Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -1360,6 +1360,31 @@ colorPicker({ value: colorVal, onChange: (c) => toast.success(c) })
 
 现场演示：apps/docs/demo.html#sec-colorpicker
 
+### tour — 引导漫游 Tour
+
+参数：
+
+- steps（必填）：TourStep[] —— 步骤序列：每步含 target 选择器、title、可选 description
+- padding：number —— 聚光区相对目标的外扩像素；缺省 6
+- onFinish：() => void —— 走完最后一步的回调
+- onClose：() => void —— 中途跳过（× 或 Esc）的回调
+
+示例：
+
+```
+const t = tour({ steps: [{ target: '#sec-tour', title: '引导漫游', description: '按选择器定位' }], onFinish: () => toast.success('完成') }); document.body.append(t.el); t.start();
+```
+
+手把手：
+
+1. tour() 返回 { el, start, close } 句柄：el 必须挂到 body（fixed 定位，不占布局）
+2. start() 从第一步播放，可重复调用重播；close() 立即退出并按跳过处理
+3. 聚光框按 target 选择器定位并外扩 padding，其余区域由超大 box-shadow 压暗（省掉独立遮罩层）
+4. 卡片优先落在目标下方，空间不足自动翻到上方，左右夹在视口内；滚动 / 缩放会实时重算
+5. 末步按钮文案变「完成」并触发 onFinish；× 或 Esc 触发 onClose，焦点归还开启前的元素
+
+现场演示：apps/docs/demo.html#sec-tour
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -1415,6 +1440,7 @@ API 速览：
 - datePicker(props)：日期选择，单月网格 + 翻月 / 今天快捷键，value 为 YYYY-MM-DD 信号，min/max 闭区间限制，方向键逐日逐周可导航
 - backTop(props)：返回顶部悬浮按钮，越过阈值才浮现，外环 conic-gradient 显示已滚比例，点击平滑回顶
 - colorPicker(props)：颜色选择，预设色板（缺省语义令牌色）+ 原生取色器 + 手输 CSS 颜色串，value 为颜色串信号
+- tour(props)：引导漫游，返回 { el, start, close } 句柄；聚光框按 target 选择器定位，卡片自动选方位，Esc / 跳过走 onClose
 
 一行用法：