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

packages/skin/ui/src/index.ts

@@ -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';

packages/skin/ui/src/popover.ts

@@ -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;
+}

packages/skin/ui/src/types.ts

@@ -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;   // 按钮文案