@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/popconfirm/index.tsx

@@ -0,0 +1,477 @@
+/**
+ * 气泡确认 Popconfirm
+ *
+ * 基于 Popover 的语义特化套件 — 用于小风险操作的二次确认（删除、忽略、提交审批等），
+ * 视觉比 AlertDialog 更轻、不阻塞页面；支持 onConfirm 返回 Promise 自动 loading。
+ *
+ * @when
+ * - 列表行级删除二次确认
+ * - 忽略 / 跳过等轻量确认动作
+ * - 不需要全屏模态遮罩的确认场景
+ *
+ * 组合结构：Popconfirm > PopconfirmTrigger + PopconfirmContent (> PopconfirmHeader > PopconfirmIcon + PopconfirmTitle + PopconfirmDescription | PopconfirmFooter > PopconfirmCancel + PopconfirmAction | PopconfirmArrow)
+ *
+ * 提供两种心智：
+ * - 单体便捷：`<Popconfirm title onConfirm><Button/></Popconfirm>` — 高频一行调用
+ * - Composable：`<PopconfirmRoot><PopconfirmTrigger/><PopconfirmContent><PopconfirmHeader/>...</PopconfirmContent></PopconfirmRoot>`
+ */
+'use client';
+
+import * as React from 'react';
+import { Popover as PopoverPrimitive } from 'radix-ui';
+import { AlertCircleIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Button, type ButtonProps } from '@/components/button';
+import {
+  Popover,
+  PopoverArrow,
+  PopoverContent,
+  PopoverTrigger,
+  type PopoverContentProps,
+  type PopoverProps,
+} from '@/components/popover';
+
+// ─── Context ─────────────────────────────────────────────────────────────────
+
+interface PopconfirmContextValue {
+  /** 确认按钮 loading 状态（async 自动管理或受控 */
+  loading: boolean;
+  /** intent 语义意图，驱动 icon 颜色与 Action 按钮 variant */
+  intent: 'default' | 'warning' | 'destructive';
+  /** 关闭气泡（PopconfirmAction async 完成后自动调用） */
+  close: () => void;
+  /** 设置内部 loading（PopconfirmAction async onClick 内部使用） */
+  setLoading: (next: boolean) => void;
+  /** loading 是否被外部受控（true 时 setLoading 仅做 noop） */
+  loadingControlled: boolean;
+}
+
+const PopconfirmContext = React.createContext<PopconfirmContextValue | null>(
+  null,
+);
+
+function usePopconfirmContext(component: string): PopconfirmContextValue {
+  const ctx = React.useContext(PopconfirmContext);
+  if (!ctx) {
+    throw new Error(
+      `${component} 必须在 <PopconfirmContent> 内部使用（或使用单体 <Popconfirm/>）。`,
+    );
+  }
+  return ctx;
+}
+
+// ─── Composable Root / Trigger（薄壳） ──────────────────────────────────────
+
+/**
+ * Popconfirm composable Root — 气泡确认根容器（Popover 薄壳）。
+ *
+ * 用于完全自由组合的场景；单体便捷形态请使用 `Popconfirm` 默认导出。
+ */
+function PopconfirmRoot({ ...props }: PopoverProps) {
+  return <Popover data-slot="popconfirm" {...props} />;
+}
+
+/** 气泡确认触发节点 — `asChild` 接管自定义触发器。 */
+function PopconfirmTrigger({
+  ...props
+}: React.ComponentProps<typeof PopoverTrigger>) {
+  return <PopoverTrigger data-slot="popconfirm-trigger" {...props} />;
+}
+
+// ─── PopconfirmContent（双形态核心） ─────────────────────────────────────────
+
+export interface PopconfirmContentProps
+  extends Omit<PopoverContentProps, 'title'> {
+  /** 确认标题 — 便捷模式渲染 PopconfirmTitle */
+  title?: React.ReactNode;
+  /** 补充描述 — 便捷模式渲染 PopconfirmDescription */
+  description?: React.ReactNode;
+  /** 自定义图标 — 默认 AlertCircleIcon，跟随 intent 上色 */
+  icon?: React.ReactNode;
+  /** 语义意图，控制 icon 颜色与 Action 按钮 variant @default "default" */
+  intent?: 'default' | 'warning' | 'destructive';
+  /** 确认按钮文本 @default "确定" */
+  okText?: React.ReactNode;
+  /** 取消按钮文本 @default "取消" */
+  cancelText?: React.ReactNode;
+  /** 确认按钮额外 props（业界对齐 antd okButtonProps） */
+  okButtonProps?: ButtonProps;
+  /** 取消按钮额外 props */
+  cancelButtonProps?: ButtonProps;
+  /** 确认回调，async 自动管理 loading + 关闭 */
+  onConfirm?: () => void | Promise<void>;
+  /** 取消回调（Cancel 按钮点击触发，气泡始终关闭） */
+  onCancel?: () => void;
+  /** 受控 loading（覆盖 async 自动管理） */
+  loading?: boolean;
+  /** 便捷模式是否显示菱形箭头 @default true */
+  showArrow?: boolean;
+}
+
+function PopconfirmContent({
+  className,
+  children,
+  title,
+  description,
+  icon,
+  intent = 'default',
+  okText = '确定',
+  cancelText = '取消',
+  okButtonProps,
+  cancelButtonProps,
+  onConfirm,
+  onCancel,
+  loading: loadingProp,
+  showArrow = true,
+  align = 'start',
+  ...rest
+}: PopconfirmContentProps) {
+  const [internalLoading, setInternalLoading] = React.useState(false);
+  const loadingControlled = loadingProp !== undefined;
+  const loading = loadingControlled ? !!loadingProp : internalLoading;
+
+  // 通过 PopoverClose ref 触发关闭，避免重复维护 open 状态
+  const closeRef = React.useRef<HTMLButtonElement>(null);
+  const close = React.useCallback(() => {
+    closeRef.current?.click();
+  }, []);
+
+  const ctx = React.useMemo<PopconfirmContextValue>(
+    () => ({
+      loading,
+      intent,
+      close,
+      setLoading: (next) => {
+        if (!loadingControlled) setInternalLoading(next);
+      },
+      loadingControlled,
+    }),
+    [loading, intent, close, loadingControlled],
+  );
+
+  const isComposable = children !== undefined;
+
+  return (
+    <PopoverContent
+      data-slot="popconfirm-content"
+      data-intent={intent}
+      align={align}
+      className={cn('w-64 p-3', className)}
+      {...rest}
+    >
+      <PopconfirmContext.Provider value={ctx}>
+        {/* 隐藏的 Radix Close 用于 close() 编程式触发（不用本库 PopoverClose—后者带右上角绝对定位样式会污染 child） */}
+        <PopoverPrimitive.Close
+          ref={closeRef}
+          aria-hidden
+          tabIndex={-1}
+          className="hidden"
+        />
+        {isComposable ? (
+          children
+        ) : (
+          <>
+            <PopconfirmHeader
+              className={description ? 'items-start' : 'items-center'}
+            >
+              <PopconfirmIcon>{icon}</PopconfirmIcon>
+              <div className="min-w-0 flex-1">
+                {title ? <PopconfirmTitle>{title}</PopconfirmTitle> : null}
+                {description ? (
+                  <PopconfirmDescription>{description}</PopconfirmDescription>
+                ) : null}
+              </div>
+            </PopconfirmHeader>
+            <PopconfirmFooter>
+              <PopconfirmCancel onClick={onCancel} {...cancelButtonProps}>
+                {cancelButtonProps?.children ?? cancelText}
+              </PopconfirmCancel>
+              <PopconfirmAction onClick={onConfirm} {...okButtonProps}>
+                {okButtonProps?.children ?? okText}
+              </PopconfirmAction>
+            </PopconfirmFooter>
+            {showArrow ? <PopconfirmArrow /> : null}
+          </>
+        )}
+      </PopconfirmContext.Provider>
+    </PopoverContent>
+  );
+}
+
+// ─── 子组件（composable） ────────────────────────────────────────────────────
+
+/** 标题 + 图标行容器。 */
+function PopconfirmHeader({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="popconfirm-header"
+      className={cn('flex items-start gap-2', className)}
+      {...props}
+    />
+  );
+}
+
+/** 标题前的语义图标插槽（默认 AlertCircleIcon，跟随 intent 上色）。 */
+function PopconfirmIcon({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<'span'>) {
+  const ctx = React.useContext(PopconfirmContext);
+  const intent = ctx?.intent ?? 'default';
+  return (
+    <span
+      data-slot="popconfirm-icon"
+      data-intent={intent}
+      className={cn(
+        'inline-flex h-4 shrink-0 items-center',
+        intent === 'destructive' ? 'text-destructive' : 'text-warning',
+        className,
+      )}
+      {...props}
+    >
+      {children ?? <AlertCircleIcon className="size-4" />}
+    </span>
+  );
+}
+
+/** 气泡确认标题。 */
+function PopconfirmTitle({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="popconfirm-title"
+      className={cn('text-xs font-medium', className)}
+      {...props}
+    />
+  );
+}
+
+/** 气泡确认描述。 */
+function PopconfirmDescription({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="popconfirm-description"
+      className={cn('mt-1 text-xs text-muted-foreground', className)}
+      {...props}
+    />
+  );
+}
+
+/** 按钮区容器（默认右对齐）。 */
+function PopconfirmFooter({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="popconfirm-footer"
+      className={cn('mt-3 flex justify-end gap-2', className)}
+      {...props}
+    />
+  );
+}
+
+/** 取消按钮 — 点击始终关闭气泡，并触发可选 onClick。 */
+function PopconfirmCancel({
+  className,
+  variant = 'outline',
+  size = 'sm',
+  ...props
+}: ButtonProps) {
+  return (
+    <PopoverPrimitive.Close asChild>
+      <Button
+        data-slot="popconfirm-cancel"
+        variant={variant}
+        size={size}
+        className={className}
+        {...props}
+      />
+    </PopoverPrimitive.Close>
+  );
+}
+
+/** 确认按钮 — 自动 await async onClick + 锁定 + 完成后关闭气泡。 */
+function PopconfirmAction({
+  className,
+  size = 'sm',
+  variant,
+  disabled,
+  loading: loadingProp,
+  onClick,
+  ...props
+}: ButtonProps) {
+  const ctx = usePopconfirmContext('PopconfirmAction');
+  const resolvedVariant =
+    variant ?? (ctx.intent === 'destructive' ? 'destructive' : 'default');
+  // 优先 prop 受控，其次 context 自动管理的 loading
+  const loading = loadingProp ?? ctx.loading;
+
+  const handleClick = async (event: React.MouseEvent<HTMLButtonElement>) => {
+    if (!onClick) {
+      ctx.close();
+      return;
+    }
+    try {
+      ctx.setLoading(true);
+      const ret: unknown = onClick(event);
+      if (ret && typeof (ret as { then?: unknown }).then === 'function') {
+        await (ret as Promise<unknown>);
+      }
+      ctx.close();
+    } finally {
+      ctx.setLoading(false);
+    }
+  };
+
+  return (
+    <Button
+      data-slot="popconfirm-action"
+      variant={resolvedVariant}
+      size={size}
+      disabled={disabled}
+      loading={loading}
+      onClick={handleClick}
+      className={className}
+      {...props}
+    />
+  );
+}
+
+/** 菱形箭头（沿用 Popover Balloon 风格，半嵌入式）。 */
+function PopconfirmArrow({
+  ...props
+}: React.ComponentProps<typeof PopoverArrow>) {
+  return <PopoverArrow data-slot="popconfirm-arrow" {...props} />;
+}
+
+// ─── 单体便捷形态 ────────────────────────────────────────────────────────────
+
+export interface PopconfirmProps {
+  /** 触发节点（通常是 Button / Link）。 */
+  children: React.ReactElement;
+  /** 确认标题。 */
+  title?: React.ReactNode;
+  /** 补充描述 — 解释操作后果。 */
+  description?: React.ReactNode;
+  /** 标题前图标 — 默认警示图标，跟随 intent 上色。 */
+  icon?: React.ReactNode;
+  /** 语义意图，控制 icon 颜色与 Action 按钮 variant。 @default "default" */
+  intent?: 'default' | 'warning' | 'destructive';
+  /** 确认按钮文本。 @default "确定" */
+  okText?: React.ReactNode;
+  /** 取消按钮文本。 @default "取消" */
+  cancelText?: React.ReactNode;
+  /** 确认按钮额外 props（业界对齐 antd okButtonProps）。 */
+  okButtonProps?: ButtonProps;
+  /** 取消按钮额外 props。 */
+  cancelButtonProps?: ButtonProps;
+  /** 确认回调（支持 async，loading 自动管理 + 完成后关闭）。 */
+  onConfirm?: () => void | Promise<void>;
+  /** 取消回调（气泡始终关闭）。 */
+  onCancel?: () => void;
+  /** 受控 loading（覆盖 async 自动管理）。 */
+  loading?: boolean;
+  /** 受控 open — 不传时组件自管状态。 */
+  open?: boolean;
+  /** 非受控初始 open。 @default false */
+  defaultOpen?: boolean;
+  /** open 变化回调。 */
+  onOpenChange?: (next: boolean) => void;
+  /** 是否模态（阻止外部交互）。 @default false */
+  modal?: boolean;
+  /** 禁用（不弹出确认，直接渲染 children）。 @default false */
+  disabled?: boolean;
+  /** 弹出方向。 */
+  side?: 'top' | 'right' | 'bottom' | 'left';
+  /** 对齐。 @default "start" */
+  align?: 'start' | 'center' | 'end';
+  /** 距离触发器的偏移量。 */
+  sideOffset?: number;
+  /** 是否显示菱形箭头。 @default true */
+  showArrow?: boolean;
+  /** Portal 渲染容器。 @default document.body */
+  container?: HTMLElement | null;
+  /** 自定义 PopconfirmContent className。 */
+  className?: string;
+}
+
+function Popconfirm({
+  children,
+  title,
+  description,
+  icon,
+  intent = 'default',
+  okText,
+  cancelText,
+  okButtonProps,
+  cancelButtonProps,
+  onConfirm,
+  onCancel,
+  loading,
+  open,
+  defaultOpen,
+  onOpenChange,
+  modal,
+  disabled = false,
+  side,
+  align = 'start',
+  sideOffset,
+  showArrow = true,
+  container,
+  className,
+}: PopconfirmProps) {
+  if (disabled) return children;
+
+  return (
+    <PopconfirmRoot
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+      modal={modal}
+    >
+      <PopconfirmTrigger asChild>{children}</PopconfirmTrigger>
+      <PopconfirmContent
+        title={title}
+        description={description}
+        icon={icon}
+        intent={intent}
+        okText={okText}
+        cancelText={cancelText}
+        okButtonProps={okButtonProps}
+        cancelButtonProps={cancelButtonProps}
+        onConfirm={onConfirm}
+        onCancel={onCancel}
+        loading={loading}
+        showArrow={showArrow}
+        side={side}
+        align={align}
+        sideOffset={sideOffset}
+        container={container}
+        className={className}
+      />
+    </PopconfirmRoot>
+  );
+}
+
+export {
+  Popconfirm,
+  PopconfirmAction,
+  PopconfirmArrow,
+  PopconfirmCancel,
+  PopconfirmContent,
+  PopconfirmDescription,
+  PopconfirmFooter,
+  PopconfirmHeader,
+  PopconfirmIcon,
+  PopconfirmRoot,
+  PopconfirmTitle,
+  PopconfirmTrigger,
+};

package/src/components/popconfirm/meta.md

@@ -0,0 +1,164 @@
+# PopconfirmContent
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+气泡确认 Popconfirm
+基于 Popover 的语义特化套件 — 用于小风险操作的二次确认（删除、忽略、提交审批等），
+视觉比 AlertDialog 更轻、不阻塞页面；支持 onConfirm 返回 Promise 自动 loading。
+
+## 使用场景
+
+- 列表行级删除二次确认
+- 忽略 / 跳过等轻量确认动作
+- 不需要全屏模态遮罩的确认场景
+- 组合结构：Popconfirm > PopconfirmTrigger + PopconfirmContent (> PopconfirmHeader > PopconfirmIcon + PopconfirmTitle + PopconfirmDescription | PopconfirmFooter > PopconfirmCancel + PopconfirmAction | PopconfirmArrow)
+- 提供两种心智：
+- 单体便捷：`<Popconfirm title onConfirm><Button/></Popconfirm>` — 高频一行调用
+- Composable：`<PopconfirmRoot><PopconfirmTrigger/><PopconfirmContent><PopconfirmHeader/>...</PopconfirmContent></PopconfirmRoot>`
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `title` | `React.ReactNode` | – | – | 确认标题 — 便捷模式渲染 PopconfirmTitle |
+| `description` | `React.ReactNode` | – | – | 补充描述 — 便捷模式渲染 PopconfirmDescription |
+| `icon` | `React.ReactNode` | – | – | 自定义图标 — 默认 AlertCircleIcon，跟随 intent 上色 |
+| `intent` | `'default' \| 'warning' \| 'destructive'` | `"default"` | – | 语义意图，控制 icon 颜色与 Action 按钮 variant |
+| `okText` | `React.ReactNode` | `"确定"` | – | 确认按钮文本 |
+| `cancelText` | `React.ReactNode` | `"取消"` | – | 取消按钮文本 |
+| `okButtonProps` | `ButtonProps` | – | – | 确认按钮额外 props（业界对齐 antd okButtonProps） |
+| `cancelButtonProps` | `ButtonProps` | – | – | 取消按钮额外 props |
+| `onConfirm` | `() => void \| Promise<void>` | – | – | 确认回调，async 自动管理 loading + 关闭 |
+| `onCancel` | `() => void` | – | – | 取消回调（Cancel 按钮点击触发，气泡始终关闭） |
+| `loading` | `boolean` | – | – | 受控 loading（覆盖 async 自动管理） |
+| `showArrow` | `boolean` | `true` | – | 便捷模式是否显示菱形箭头 |
+| `children` | `React.ReactElement` | – | ✓ | 触发节点（通常是 Button / Link）。 |
+| `title` | `React.ReactNode` | – | – | 确认标题。 |
+| `description` | `React.ReactNode` | – | – | 补充描述 — 解释操作后果。 |
+| `icon` | `React.ReactNode` | – | – | 标题前图标 — 默认警示图标，跟随 intent 上色。 |
+| `intent` | `'default' \| 'warning' \| 'destructive'` | `"default"` | – | 语义意图，控制 icon 颜色与 Action 按钮 variant。 |
+| `okText` | `React.ReactNode` | `"确定"` | – | 确认按钮文本。 |
+| `cancelText` | `React.ReactNode` | `"取消"` | – | 取消按钮文本。 |
+| `okButtonProps` | `ButtonProps` | – | – | 确认按钮额外 props（业界对齐 antd okButtonProps）。 |
+| `cancelButtonProps` | `ButtonProps` | – | – | 取消按钮额外 props。 |
+| `onConfirm` | `() => void \| Promise<void>` | – | – | 确认回调（支持 async，loading 自动管理 + 完成后关闭）。 |
+| `onCancel` | `() => void` | – | – | 取消回调（气泡始终关闭）。 |
+| `loading` | `boolean` | – | – | 受控 loading（覆盖 async 自动管理）。 |
+| `open` | `boolean` | – | – | 受控 open — 不传时组件自管状态。 |
+| `defaultOpen` | `boolean` | `false` | – | 非受控初始 open。 |
+| `onOpenChange` | `(next: boolean) => void` | – | – | open 变化回调。 |
+| `modal` | `boolean` | `false` | – | 是否模态（阻止外部交互）。 |
+| `disabled` | `boolean` | `false` | – | 禁用（不弹出确认，直接渲染 children）。 |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | – | – | 弹出方向。 |
+| `align` | `'start' \| 'center' \| 'end'` | `"start"` | – | 对齐。 |
+| `sideOffset` | `number` | – | – | 距离触发器的偏移量。 |
+| `showArrow` | `boolean` | `true` | – | 是否显示菱形箭头。 |
+| `container` | `HTMLElement \| null` | `document.body` | – | Portal 渲染容器。 |
+| `className` | `string` | – | – | 自定义 PopconfirmContent className。 |
+
+## 示例
+
+### Destructive
+
+```tsx
+<Popconfirm
+  title="确定删除此记录？"
+  description="删除后数据将不可恢复。"
+  intent="destructive"
+  okText="删除"
+  onConfirm={() => console.log('deleted')}
+>
+  <Button variant="destructive">删除</Button>
+</Popconfirm>
+```
+
+### WithDescription
+
+```tsx
+<Popconfirm
+  title="确定提交审批？"
+  description="提交后将通知审批人，预计 1 个工作日处理。"
+  onConfirm={() => console.log('submitted')}
+>
+  <Button>提交</Button>
+</Popconfirm>
+```
+
+### AsyncConfirm
+
+```tsx
+<Popconfirm
+  title="确定提交？"
+  description="提交后将发送审批请求。"
+  onConfirm={() => new Promise((r) => setTimeout(r, 1500))}
+>
+  <Button>提交审批</Button>
+</Popconfirm>
+```
+
+### CustomButtons
+
+```tsx
+<Popconfirm
+  title="确定离开？"
+  description="未保存的修改将丢失。"
+  okButtonProps={{ size: 'default', children: '离开并丢弃' }}
+  cancelButtonProps={{ size: 'default', children: '继续编辑' }}
+  onConfirm={() => console.log('left')}
+>
+  <Button>离开</Button>
+</Popconfirm>
+```
+
+### WithoutArrow
+
+```tsx
+<div className="flex gap-4">
+  <Popconfirm title="带箭头" onConfirm={() => {}}>
+    <Button>默认</Button>
+  </Popconfirm>
+  <Popconfirm title="无箭头" showArrow={false} onConfirm={() => {}}>
+    <Button>无箭头</Button>
+  </Popconfirm>
+</div>
+```
+
+### Disabled
+
+```tsx
+<Popconfirm title="不会弹出" disabled onConfirm={() => {}}>
+  <Button>禁用</Button>
+</Popconfirm>
+```
+
+### Composable
+
+```tsx
+<PopconfirmRoot>
+  <PopconfirmTrigger asChild>
+    <Button>触发</Button>
+  </PopconfirmTrigger>
+  <PopconfirmContent intent="destructive">
+    <PopconfirmHeader>
+      <PopconfirmIcon />
+      <div className="min-w-0 flex-1">
+        <PopconfirmTitle>确定移除该成员？</PopconfirmTitle>
+        <PopconfirmDescription>
+          移除后该成员将失去当前空间访问权限。
+        </PopconfirmDescription>
+      </div>
+    </PopconfirmHeader>
+    <PopconfirmFooter>
+      <PopconfirmCancel>取消</PopconfirmCancel>
+      <PopconfirmAction
+        onClick={() => new Promise((r) => setTimeout(r, 1200))}
+      >
+        移除
+      </PopconfirmAction>
+    </PopconfirmFooter>
+    <PopconfirmArrow />
+  </PopconfirmContent>
+</PopconfirmRoot>
+```