iter: d07 新增可交互气泡卡片 popover

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-23T08:50:48.366Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-23T08:51:47.072Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -40,7 +40,7 @@
 
 ## @ui-arch/ui（skin-dom）v0.1.0
 
-23 个 DOM 组件，统一用法：组件是普通函数，传入 props 返回 DOM 节点；需要状态时先创建 signal 再双向绑定。引入 CSS：import '@ui-arch/ui/ui.css'（内部已消费 tokens）。
+24 个 DOM 组件，统一用法：组件是普通函数，传入 props 返回 DOM 节点；需要状态时先创建 signal 再双向绑定。引入 CSS：import '@ui-arch/ui/ui.css'（内部已消费 tokens）。
 
 ### button — 按钮 Button
 
@@ -415,6 +415,34 @@ tooltip({ content: '保存后立即生效' }, button({ label: '保存', onClick:
 
 现场演示：apps/docs/demo.html#sec-tooltip
 
+### popover — 气泡卡片 Popover
+
+参数：
+
+- content（必填）：unknown —— 弹层内容：字符串 / DOM 节点 / 响应式函数，可放按钮等交互元素
+- title：string —— 弹层标题；缺省不渲染标题行
+- placement（默认 bottom）：'top' | 'bottom' —— 弹层方位；缺省 bottom（触发器下方）
+- trigger（默认 click）：'click' | 'hover' —— 触发方式；缺省 click
+- delay（默认 150）：number —— hover 模式出场延迟毫秒；缺省 150
+- onOpenChange（回调）：(open: boolean) => void —— 开合回调
+- triggerEl（第二个参数）（必填）：HTMLElement —— 第二个参数：被包裹的触发器元素
+
+示例：
+
+```
+popover({ title: '筛选条件', content: h('div', null, '任意可交互内容') }, button({ label: '筛选' }))
+```
+
+手把手：
+
+1. 创建触发器元素，再用 popover(props, trigger) 包一层：返回带弹层的包裹元素
+2. 点击触发器开合；点弹层外部或按 Esc 收起（Esc 后焦点回触发器）
+3. content 里可以放 button / checkbox 等交互元素（tooltip 只能纯文本），点击弹层内部不会误关
+4. hover 场景传 trigger: 'hover' + delay 控制多快出场；placement: 'top' 让弹层往上翻
+5. 需要感知开合做副作用（如懒加载数据）时用 onOpenChange
+
+现场演示：apps/docs/demo.html#sec-popover
+
 ### spinner — 加载指示器 Spinner
 
 参数：
@@ -608,6 +636,7 @@ API 速览：
 - alert(props)：提示条，variant = info | success | warning | danger
 - toast.info/success/warning/error(message, duration?)：消息提示工厂，右上角堆叠，默认 3s 自动消失，出入场微动画；showToast(props) 为完整入参版本
 - tooltip(props, trigger)：悬浮提示，包裹触发器，hover / focus 延迟 150ms 出场，移出 / 失焦 / Esc 收起
+- popover(props, trigger)：可交互气泡卡片，包裹触发器，默认点击开合 + 点外部 / Esc 收起，content 可放按钮等交互元素
 - skeleton(props)：骨架屏占位，variant = text | rect | circle，text 支持 rows 多行，扫光微动画
 - pagination(props)：独立分页器，page 信号双向绑定，页码过多折叠省略号，首末页禁用翻页，键盘可达
 - spinner(props)：加载指示器，size 控制直径