@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/popconfirm/stories.tsx

@@ -0,0 +1,231 @@
+/**
+ * @fileoverview Popconfirm stories — 气泡确认演示（双形态：单体便捷 + composable）
+ */
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import {
+  Popconfirm,
+  PopconfirmAction,
+  PopconfirmArrow,
+  PopconfirmCancel,
+  PopconfirmContent,
+  PopconfirmDescription,
+  PopconfirmFooter,
+  PopconfirmHeader,
+  PopconfirmIcon,
+  PopconfirmRoot,
+  PopconfirmTitle,
+  PopconfirmTrigger,
+} from '.';
+import { Button } from '@/components/button';
+
+const meta: Meta<typeof Popconfirm> = {
+  title: '反馈 · Feedback/Popconfirm 气泡确认框',
+  component: Popconfirm,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '基于 Popover 的语义特化套件 — 用于小风险操作的二次确认，支持 onConfirm Promise 自动 loading；提供单体便捷与 composable 两种心智。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Popconfirm>;
+
+// ─── 1. 基础用法 ─────────────────────────────────────────────────────────────
+
+export const Default: Story = {
+  name: '基础用法',
+  render: () => (
+    <Popconfirm
+      title="确定执行此操作？"
+      onConfirm={() => console.log('confirmed')}
+    >
+      <Button>触发</Button>
+    </Popconfirm>
+  ),
+};
+
+// ─── 2. 危险操作 ─────────────────────────────────────────────────────────────
+
+export const Destructive: Story = {
+  name: '危险操作（intent=destructive）',
+  render: () => (
+    <Popconfirm
+      title="确定删除此记录？"
+      description="删除后数据将不可恢复。"
+      intent="destructive"
+      okText="删除"
+      onConfirm={() => console.log('deleted')}
+    >
+      <Button variant="destructive">删除</Button>
+    </Popconfirm>
+  ),
+};
+
+// ─── 3. 含描述 ───────────────────────────────────────────────────────────────
+
+export const WithDescription: Story = {
+  name: '含描述',
+  render: () => (
+    <Popconfirm
+      title="确定提交审批？"
+      description="提交后将通知审批人，预计 1 个工作日处理。"
+      onConfirm={() => console.log('submitted')}
+    >
+      <Button>提交</Button>
+    </Popconfirm>
+  ),
+};
+
+// ─── 4. 异步确认 ─────────────────────────────────────────────────────────────
+
+export const AsyncConfirm: Story = {
+  name: '异步确认（自动 loading）',
+  render: () => (
+    <Popconfirm
+      title="确定提交？"
+      description="提交后将发送审批请求。"
+      onConfirm={() => new Promise((r) => setTimeout(r, 1500))}
+    >
+      <Button>提交审批</Button>
+    </Popconfirm>
+  ),
+};
+
+// ─── 5. 受控 ────────────────────────────────────────────────────────────────
+
+export const Controlled: Story = {
+  name: '受控 open',
+  render: () => {
+    const ControlledDemo = () => {
+      const [open, setOpen] = React.useState(false);
+      return (
+        <div className="flex items-center gap-4">
+          <Popconfirm
+            open={open}
+            onOpenChange={setOpen}
+            title="受控确认"
+            description="open / onOpenChange 受外部驱动。"
+            onConfirm={() => console.log('confirmed')}
+          >
+            <Button>触发</Button>
+          </Popconfirm>
+          <span className="text-xs text-muted-foreground">
+            当前：{open ? '打开' : '关闭'}
+          </span>
+        </div>
+      );
+    };
+    return <ControlledDemo />;
+  },
+};
+
+// ─── 6. 自定义按钮 ───────────────────────────────────────────────────────────
+
+export const CustomButtons: Story = {
+  name: '自定义按钮 props',
+  render: () => (
+    <Popconfirm
+      title="确定离开？"
+      description="未保存的修改将丢失。"
+      okButtonProps={{ size: 'default', children: '离开并丢弃' }}
+      cancelButtonProps={{ size: 'default', children: '继续编辑' }}
+      onConfirm={() => console.log('left')}
+    >
+      <Button>离开</Button>
+    </Popconfirm>
+  ),
+};
+
+// ─── 7. 无箭头 ───────────────────────────────────────────────────────────────
+
+export const WithoutArrow: Story = {
+  name: '无箭头（showArrow=false）',
+  render: () => (
+    <div className="flex gap-4">
+      <Popconfirm title="带箭头" onConfirm={() => {}}>
+        <Button>默认</Button>
+      </Popconfirm>
+      <Popconfirm title="无箭头" showArrow={false} onConfirm={() => {}}>
+        <Button>无箭头</Button>
+      </Popconfirm>
+    </div>
+  ),
+};
+
+// ─── 8. 弹出方向 ─────────────────────────────────────────────────────────────
+
+export const Placement: Story = {
+  name: '弹出方向',
+  render: () => {
+    const sides = ['top', 'right', 'bottom', 'left'] as const;
+    const aligns = ['start', 'center', 'end'] as const;
+    return (
+      <div className="grid grid-cols-3 gap-4">
+        {sides.flatMap((side) =>
+          aligns.map((align) => (
+            <Popconfirm
+              key={`${side}-${align}`}
+              title={`${side} / ${align}`}
+              side={side}
+              align={align}
+              onConfirm={() => {}}
+            >
+              <Button>{`${side}-${align}`}</Button>
+            </Popconfirm>
+          )),
+        )}
+      </div>
+    );
+  },
+};
+
+// ─── 9. 禁用 ────────────────────────────────────────────────────────────────
+
+export const Disabled: Story = {
+  name: '禁用（disabled）',
+  render: () => (
+    <Popconfirm title="不会弹出" disabled onConfirm={() => {}}>
+      <Button>禁用</Button>
+    </Popconfirm>
+  ),
+};
+
+// ─── 10. Composable 完全自由组合 ─────────────────────────────────────────────
+
+export const Composable: Story = {
+  name: 'Composable 子组件',
+  render: () => (
+    <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>
+  ),
+};

package/src/components/popover/index.tsx

@@ -0,0 +1,181 @@
+/**
+ * 气泡卡片 Popover
+ *
+ * 点击触发的弹出层，展示富交互内容；可选关闭按钮、尖角箭头、自定义渲染容器。
+ *
+ * @when
+ * - 需要点击后展示较复杂的操作面板
+ * - 筛选器、颜色选择器等小型表单
+ * - 确认操作（Popconfirm 基础）
+ *
+ * 组合结构：Popover > PopoverTrigger + PopoverContent (> PopoverHeader > PopoverTitle + PopoverDescription | PopoverClose | PopoverArrow)
+ */
+
+'use client';
+
+import * as React from 'react';
+import { Popover as PopoverPrimitive, Slot } from 'radix-ui';
+import { XIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+
+export interface PopoverProps
+  extends Omit<
+    React.ComponentProps<typeof PopoverPrimitive.Root>,
+    'open' | 'defaultOpen' | 'onOpenChange' | 'modal'
+  > {
+  /** 受控显示状态。 */
+  open?: boolean;
+  /** 非受控初始显示状态。 @default false */
+  defaultOpen?: boolean;
+  /**
+   * 显示 / 关闭状态变化回调。
+   * @param open 当前是否显示
+   */
+  onOpenChange?: (open: boolean) => void;
+  /** 是否模态（阻止外部交互）。 @default false */
+  modal?: boolean;
+}
+
+function Popover({ ...props }: PopoverProps) {
+  return <PopoverPrimitive.Root data-slot="popover" {...props} />;
+}
+
+function PopoverTrigger({
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Trigger>) {
+  return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />;
+}
+
+export interface PopoverContentProps
+  extends React.ComponentProps<typeof PopoverPrimitive.Content> {
+  /** 浮层渲染容器，透传给 Portal。 @default document.body */
+  container?: HTMLElement | null;
+}
+
+function PopoverContent({
+  className,
+  align = 'center',
+  sideOffset = 4,
+  container,
+  ...props
+}: PopoverContentProps) {
+  return (
+    <PopoverPrimitive.Portal container={container}>
+      <PopoverPrimitive.Content
+        data-slot="popover-content"
+        align={align}
+        sideOffset={sideOffset}
+        className={cn(
+          'group/popover-content relative z-50 flex w-72 origin-(--radix-popover-content-transform-origin) flex-col gap-2.5 rounded-md bg-popover p-2.5 text-xs text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+          className,
+        )}
+        {...props}
+      />
+    </PopoverPrimitive.Portal>
+  );
+}
+
+function PopoverAnchor({
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Anchor>) {
+  return <PopoverPrimitive.Anchor data-slot="popover-anchor" {...props} />;
+}
+
+function PopoverHeader({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="popover-header"
+      className={cn('flex flex-col gap-0.5', className)}
+      {...props}
+    />
+  );
+}
+
+function PopoverTitle({ className, ...props }: React.ComponentProps<'h2'>) {
+  return (
+    <div
+      data-slot="popover-title"
+      className={cn('font-medium', className)}
+      {...props}
+    />
+  );
+}
+
+function PopoverDescription({
+  className,
+  ...props
+}: React.ComponentProps<'p'>) {
+  return (
+    <p
+      data-slot="popover-description"
+      className={cn('text-muted-foreground', className)}
+      {...props}
+    />
+  );
+}
+
+export interface PopoverCloseProps
+  extends React.ComponentProps<typeof PopoverPrimitive.Close> {
+  /** 使用 Slot 模式渲染自定义触发器。 @default false */
+  asChild?: boolean;
+}
+
+function PopoverClose({
+  className,
+  asChild = false,
+  children,
+  ...props
+}: PopoverCloseProps) {
+  const Comp = asChild ? Slot.Root : PopoverPrimitive.Close;
+  return (
+    <Comp
+      data-slot="popover-close"
+      className={cn(
+        'absolute right-2 top-2 inline-flex size-6 cursor-pointer items-center justify-center rounded-sm text-muted-foreground opacity-70 transition-opacity hover:opacity-100 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+        className,
+      )}
+      {...props}
+    >
+      {children ?? (
+        <>
+          <XIcon className="size-3.5" />
+          <span className="sr-only">关闭</span>
+        </>
+      )}
+    </Comp>
+  );
+}
+
+function PopoverArrow({
+  className,
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Arrow>) {
+  // ant Balloon 风格：方块 rotate-45 半截嵌入 Content、半截露出。
+  // Radix Popper 已按 side 为外层 wrapper 自动旋转（top:0 / bottom:180° / left:-90° / right:90°），
+  // 所以 SVG 本地坐标系中 “朝外露出的两条边” 永远是 right + bottom，在四个方向下都是连续描边。
+  return (
+    <PopoverPrimitive.Arrow
+      data-slot="popover-arrow"
+      width={10}
+      height={10}
+      className={cn(
+        'block size-2 -translate-y-1/2 rotate-45 border-0 border-r border-b border-foreground/10 bg-popover fill-popover',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  Popover,
+  PopoverAnchor,
+  PopoverArrow,
+  PopoverClose,
+  PopoverContent,
+  PopoverDescription,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverTrigger,
+};

package/src/components/popover/meta.md

@@ -0,0 +1,97 @@
+# Popover
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+气泡卡片 Popover
+点击触发的弹出层，展示富交互内容；可选关闭按钮、尖角箭头、自定义渲染容器。
+
+## 使用场景
+
+- 需要点击后展示较复杂的操作面板
+- 筛选器、颜色选择器等小型表单
+- 确认操作（Popconfirm 基础）
+- 组合结构：Popover > PopoverTrigger + PopoverContent (> PopoverHeader > PopoverTitle + PopoverDescription | PopoverClose | PopoverArrow)
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | – | – | 受控显示状态。 |
+| `defaultOpen` | `boolean` | `false` | – | 非受控初始显示状态。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 显示 / 关闭状态变化回调。 |
+| `modal` | `boolean` | `false` | – | 是否模态（阻止外部交互）。 |
+| `container` | `HTMLElement \| null` | `document.body` | – | 浮层渲染容器，透传给 Portal。 |
+| `asChild` | `boolean` | `false` | – | 使用 Slot 模式渲染自定义触发器。 |
+
+## 示例
+
+### Alignment
+
+不同对齐方式
+
+```tsx
+<div className="flex gap-4">
+  <Popover>
+    <PopoverTrigger asChild>
+      <Button>左对齐</Button>
+    </PopoverTrigger>
+    <PopoverContent align="start">
+      <p className="text-muted-foreground">align=start 内容</p>
+    </PopoverContent>
+  </Popover>
+  <Popover>
+    <PopoverTrigger asChild>
+      <Button>居中</Button>
+    </PopoverTrigger>
+    <PopoverContent align="center">
+      <p className="text-muted-foreground">align=center 内容</p>
+    </PopoverContent>
+  </Popover>
+  <Popover>
+    <PopoverTrigger asChild>
+      <Button>右对齐</Button>
+    </PopoverTrigger>
+    <PopoverContent align="end">
+      <p className="text-muted-foreground">align=end 内容</p>
+    </PopoverContent>
+  </Popover>
+</div>
+```
+
+### WithCloseButton
+
+显示关闭按钮，覆盖 Balloon `closable` 行为。
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button>打开</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <PopoverHeader>
+      <PopoverTitle>带关闭按钮</PopoverTitle>
+      <PopoverDescription>右上角点击 X 关闭。</PopoverDescription>
+    </PopoverHeader>
+    <p className="text-muted-foreground">面板内容</p>
+    <PopoverClose />
+  </PopoverContent>
+</Popover>
+```
+
+### WithArrow
+
+显示尖角箭头。
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button>带箭头</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    提示内容
+    <PopoverArrow />
+  </PopoverContent>
+</Popover>
+```

package/src/components/popover/stories.tsx

@@ -0,0 +1,169 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Popover,
+  PopoverArrow,
+  PopoverClose,
+  PopoverContent,
+  PopoverDescription,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverTrigger,
+} from './index';
+import { Button } from '@/components/button';
+import { Input } from '@/components/input';
+import { Label } from '@/components/label';
+
+const meta: Meta<typeof Popover> = {
+  title: '数据展示 · Data Display/Popover 弹出层',
+  component: Popover,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Popover>;
+
+/** 基础弹出层 */
+export const Default: Story = {
+  render: () => (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button>打开</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <PopoverHeader>
+          <PopoverTitle>设置宽度</PopoverTitle>
+          <PopoverDescription>调整当前列的显示宽度。</PopoverDescription>
+        </PopoverHeader>
+        <div className="flex flex-col gap-2">
+          <div className="flex items-center gap-2">
+            <Label className="w-16">宽度</Label>
+            <Input defaultValue="100%" />
+          </div>
+          <div className="flex items-center gap-2">
+            <Label className="w-16">最大宽度</Label>
+            <Input defaultValue="300px" />
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  ),
+};
+
+/** 不同对齐方式 */
+export const Alignment: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      <Popover>
+        <PopoverTrigger asChild>
+          <Button>左对齐</Button>
+        </PopoverTrigger>
+        <PopoverContent align="start">
+          <p className="text-muted-foreground">align=start 内容</p>
+        </PopoverContent>
+      </Popover>
+      <Popover>
+        <PopoverTrigger asChild>
+          <Button>居中</Button>
+        </PopoverTrigger>
+        <PopoverContent align="center">
+          <p className="text-muted-foreground">align=center 内容</p>
+        </PopoverContent>
+      </Popover>
+      <Popover>
+        <PopoverTrigger asChild>
+          <Button>右对齐</Button>
+        </PopoverTrigger>
+        <PopoverContent align="end">
+          <p className="text-muted-foreground">align=end 内容</p>
+        </PopoverContent>
+      </Popover>
+    </div>
+  ),
+};
+
+/** 受控显示，点击内部按钮可程序化关闭。 */
+export const Controlled: Story = {
+  render: () => {
+    const [open, setOpen] = React.useState(false);
+    return (
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>
+          <Button>{open ? '收起' : '打开'}</Button>
+        </PopoverTrigger>
+        <PopoverContent>
+          <PopoverHeader>
+            <PopoverTitle>受控示例</PopoverTitle>
+            <PopoverDescription>open / onOpenChange 受控</PopoverDescription>
+          </PopoverHeader>
+          <div className="flex justify-end gap-2">
+            <Button size="sm" onClick={() => setOpen(false)}>
+              取消
+            </Button>
+            <Button size="sm" onClick={() => setOpen(false)}>
+              确认
+            </Button>
+          </div>
+        </PopoverContent>
+      </Popover>
+    );
+  },
+};
+
+/** 显示关闭按钮，覆盖 Balloon `closable` 行为。 */
+export const WithCloseButton: Story = {
+  render: () => (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button>打开</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <PopoverHeader>
+          <PopoverTitle>带关闭按钮</PopoverTitle>
+          <PopoverDescription>右上角点击 X 关闭。</PopoverDescription>
+        </PopoverHeader>
+        <p className="text-muted-foreground">面板内容</p>
+        <PopoverClose />
+      </PopoverContent>
+    </Popover>
+  ),
+};
+
+/** 12 方向矩阵：side × align 组合。 */
+export const AllPositions: Story = {
+  render: () => {
+    const sides = ['top', 'right', 'bottom', 'left'] as const;
+    const aligns = ['start', 'center', 'end'] as const;
+    return (
+      <div className="grid grid-cols-3 gap-4">
+        {sides.flatMap((side) =>
+          aligns.map((align) => (
+            <Popover key={`${side}-${align}`}>
+              <PopoverTrigger asChild>
+                <Button>{`${side}-${align}`}</Button>
+              </PopoverTrigger>
+              <PopoverContent side={side} align={align}>
+                <p className="text-muted-foreground">{`${side} / ${align}`}</p>
+              </PopoverContent>
+            </Popover>
+          )),
+        )}
+      </div>
+    );
+  },
+};
+
+/** 显示尖角箭头。 */
+export const WithArrow: Story = {
+  render: () => (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button>带箭头</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        提示内容
+        <PopoverArrow />
+      </PopoverContent>
+    </Popover>
+  ),
+};