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

2026-10-23 16:51:48 +08:00
parent 582318adf1
commit fb9ab88feb
11 changed files with 305 additions and 10 deletions
@@ -14,6 +14,7 @@ export { badge } from './badge.js';
 export { alert } from './alert.js';
 export { toast, showToast } from './toast.js';
 export { tooltip } from './tooltip.js';
+export { popover } from './popover.js';
 export { skeleton } from './skeleton.js';
 export { pagination } from './pagination.js';
 export { spinner } from './spinner.js';
@@ -0,0 +1,60 @@
+import { effect, h, signal } from '@ui-arch/frame';
+import type { PopoverProps } from './types.js';
+
+let seq = 0; // 全局自增序号：保证每个弹层 id 唯一，供 aria-controls 关联
+
+/*** 气泡卡片：包裹触发器，默认点击开合；内容可交互，点外部 / Esc / 再次点触发器收起 ***/
+export function popover(props: PopoverProps, trigger: HTMLElement): HTMLElement {
+  // —— 状态集中声明 ——
+  const open = signal(false);      // 弹层显隐
+  const id = `ua-pop-${++seq}`;    // 弹层唯一 id
+  let timer: number | null = null; // hover 模式下的出入场计时器
+
+  const setOpen = (next: boolean): void => {
+    if (open() === next) return;   // 幂等：状态未变不派发回调
+    open(next);
+    props.onOpenChange?.(next);
+  };
+  const toggle = (): void => setOpen(!open());
+
+  // —— 触发器与弹层 ——
+  trigger.setAttribute('aria-haspopup', 'dialog');
+  effect(() => trigger.setAttribute('aria-expanded', String(open()))); // 展开态跟随信号写回
+  const panel = h(
+    'div',
+    {
+      id,
+      class: () => `ua-pop ua-pop-${props.placement ?? 'bottom'}${open() ? ' ua-open' : ''}`,
+      role: 'dialog',
+      'aria-hidden': () => String(!open()),
+      onClick: (e: Event) => e.stopPropagation(), // 弹层内点击不触发外部关闭
+    },
+    props.title ? h('div', { class: 'ua-pop-title' }, props.title) : null,
+    h('div', { class: 'ua-pop-body' }, props.content),
+  );
+  const root = h('span', { class: 'ua-pop-wrap' }, trigger, panel);
+
+  if (props.trigger === 'hover') {
+    root.addEventListener('pointerenter', () => {
+      if (timer != null) window.clearTimeout(timer);
+      timer = window.setTimeout(() => setOpen(true), props.delay ?? 150);
+    });
+    root.addEventListener('pointerleave', () => {
+      if (timer != null) window.clearTimeout(timer); // 未出场就离开：取消计时
+      setOpen(false);
+    });
+  } else {
+    trigger.addEventListener('click', (e: Event) => {
+      e.stopPropagation(); // 阻止冒泡到 document，否则刚打开就被外部点击关掉
+      toggle();
+    });
+  }
+  root.addEventListener('keydown', (e: KeyboardEvent) => {
+    if (e.key !== 'Escape' || !open()) return; // 卫语句：未展开时 Esc 不处理
+    setOpen(false);
+    trigger.focus();                           // 收起后焦点回触发器
+  });
+  document.addEventListener('click', () => setOpen(false)); // 点外部收起（弹层内已阻止冒泡）
+
+  return root;
+}
@@ -8,6 +8,16 @@ export interface TooltipProps {
  delay?: number;              // 出场延迟毫秒；缺省 150，传 0 立即显示
 }

+/*** 气泡卡片入参 ***/
+export interface PopoverProps {
+  content: unknown;       // 弹层内容：字符串 / DOM 节点 / 响应式函数（可放交互元素）
+  title?: string;         // 弹层标题；缺省不渲染标题行
+  placement?: 'top' | 'bottom'; // 弹层方位；缺省 bottom（触发器下方）
+  trigger?: 'click' | 'hover';  // 触发方式；缺省 click（hover 模式带 delay 延迟）
+  delay?: number;         // hover 模式出场延迟毫秒；缺省 150
+  onOpenChange?: (open: boolean) => void; // 开合回调
+}
+
 /*** 按钮入参 ***/
 export interface ButtonProps {
  label: string;   // 按钮文案
@@ -1,7 +1,7 @@
 {
  "name": "@ui-arch/ui",
  "type": "skin-dom",
-  "description": "DOM 皮肤组件库：button / textField / textarea / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / alert / toast / tooltip / skeleton / spinner / progress / tabs / pagination / modal / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。",
+  "description": "DOM 皮肤组件库：button / textField / textarea / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。",
  "tags": [
    "components",
    "dom",
@@ -28,6 +28,7 @@
      "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 控制直径",
@@ -68,7 +69,8 @@
      "FormItemProps",
      "FormItemHandle",
      "FormProps",
-      "DataTableProps"
+      "DataTableProps",
+      "PopoverProps"
    ]
  },
  "usage": "const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')",
@@ -78,7 +80,7 @@
    "语义色 variant 四档：default|info / success / warning / danger，一律来自令牌，禁止硬编码颜色"
  ],
  "docs": {
-    "intro": "23 个 DOM 组件，统一用法：组件是普通函数，传入 props 返回 DOM 节点；需要状态时先创建 signal 再双向绑定。引入 CSS：import '@ui-arch/ui/ui.css'（内部已消费 tokens）。",
+    "intro": "24 个 DOM 组件，统一用法：组件是普通函数，传入 props 返回 DOM 节点；需要状态时先创建 signal 再双向绑定。引入 CSS：import '@ui-arch/ui/ui.css'（内部已消费 tokens）。",
    "steps": [
      "安装依赖：pnpm add @ui-arch/ui @ui-arch/frame（workspace 内自动链接）",
      "引入样式：在应用入口 import '@ui-arch/ui/ui.css'，暗色主题在根元素设 data-theme='dark'",
@@ -628,6 +630,62 @@
          "只做展示：不要在气泡里放可点击元素，需要交互请用 modal 或自绘弹层"
        ]
      },
+      {
+        "id": "popover",
+        "title": "气泡卡片 Popover",
+        "demo": "sec-popover",
+        "props": [
+          {
+            "n": "content",
+            "t": "unknown",
+            "r": 1,
+            "d": "弹层内容：字符串 / DOM 节点 / 响应式函数，可放按钮等交互元素"
+          },
+          {
+            "n": "title",
+            "t": "string",
+            "d": "弹层标题；缺省不渲染标题行"
+          },
+          {
+            "n": "placement",
+            "t": "'top' | 'bottom'",
+            "d": "弹层方位；缺省 bottom（触发器下方）",
+            "df": "bottom"
+          },
+          {
+            "n": "trigger",
+            "t": "'click' | 'hover'",
+            "d": "触发方式；缺省 click",
+            "df": "click"
+          },
+          {
+            "n": "delay",
+            "t": "number",
+            "d": "hover 模式出场延迟毫秒；缺省 150",
+            "df": "150"
+          },
+          {
+            "n": "onOpenChange",
+            "t": "(open: boolean) => void",
+            "k": 1,
+            "d": "开合回调"
+          },
+          {
+            "n": "triggerEl（第二个参数）",
+            "t": "HTMLElement",
+            "r": 1,
+            "d": "第二个参数：被包裹的触发器元素"
+          }
+        ],
+        "example": "popover({ title: '筛选条件', content: h('div', null, '任意可交互内容') }, button({ label: '筛选' }))",
+        "steps": [
+          "创建触发器元素，再用 popover(props, trigger) 包一层：返回带弹层的包裹元素",
+          "点击触发器开合；点弹层外部或按 Esc 收起（Esc 后焦点回触发器）",
+          "content 里可以放 button / checkbox 等交互元素（tooltip 只能纯文本），点击弹层内部不会误关",
+          "hover 场景传 trigger: 'hover' + delay 控制多快出场；placement: 'top' 让弹层往上翻",
+          "需要感知开合做副作用（如懒加载数据）时用 onOpenChange"
+        ]
+      },
      {
        "id": "spinner",
        "title": "加载指示器 Spinner",
@@ -429,6 +429,51 @@
  opacity: 0.6;
 }

+/* —— 气泡卡片（可交互弹层，与 tooltip 的分工是 content 里能点） —— */
+.ua-pop-wrap {
+  position: relative;
+  display: inline-flex;
+}
+.ua-pop {
+  position: absolute;
+  left: 0;
+  z-index: 30;
+  min-width: 200px;
+  max-width: 280px;
+  padding: var(--ua-space-3);
+  border: 1px solid var(--ua-color-border);
+  border-radius: var(--ua-radius-md);
+  background: var(--ua-color-bg);
+  box-shadow: 0 10px 28px rgba(0, 0, 0, 0.16);
+  opacity: 0;
+  visibility: hidden;
+  transition: opacity 0.16s ease, transform 0.16s ease, visibility 0.16s;
+}
+.ua-pop-top {
+  bottom: calc(100% + 8px);
+  transform: translateY(4px);
+}
+.ua-pop-bottom {
+  top: calc(100% + 8px);
+  transform: translateY(-4px);
+}
+.ua-pop.ua-open {
+  opacity: 1;
+  transform: none;
+  visibility: visible;
+}
+.ua-pop-title {
+  margin-bottom: var(--ua-space-2);
+  color: var(--ua-color-text);
+  font-size: var(--ua-font-size-lg);
+  font-weight: 600;
+}
+.ua-pop-body {
+  color: var(--ua-color-text-muted);
+  font-size: var(--ua-font-size-md);
+  line-height: 1.6;
+}
+
 /* —— 折叠面板 —— */
 .ua-accordion {
  display: flex;
@@ -999,6 +1044,7 @@
  .ua-acc-caret,
  .ua-acc-body,
  .ua-crumb-link,
+  .ua-pop,
  .ua-switch-track,
  .ua-switch-thumb,
  .ua-tab,