@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/dialog/meta.md

@@ -0,0 +1,244 @@
+# Dialog
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+对话框 Dialog
+通用模态对话框，用于展示需要用户关注的内容，基于 Radix Dialog 原语。
+采用 shadcn v4 composable 模式：所有结构以子组件显式拼装，size 通过 data-size 驱动。
+视觉规范：
+- 外层容器圆角走主题默认（`rounded-md`），自身不带 padding，由 Header / Body / Footer 各自控制
+- Header 区：`pt-3 pr-14 pb-3 pl-5`（右侧 56px 给关闭按钮预留），底部 1px 分隔线（默认 `border-border`，可 className 覆盖）
+- Body 区：`px-5 pt-4 pb-5`，默认字号 14px、颜色 muted-foreground
+- Footer 区：`px-5 py-4`，顶部分隔线默认透明
+- 关闭按钮：`absolute top-3 right-5`，可点击区 20px
+
+## 使用场景
+
+- 表单编辑弹窗
+- 详情信息展示
+- 工作流子步骤弹出层
+- 危险操作前的二次确认（推荐使用 AlertDialog）
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | – | – | 受控显示状态。 |
+| `defaultOpen` | `boolean` | `false` | – | 非受控初始显示状态。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 显示 / 关闭状态变化回调。 |
+| `modal` | `boolean` | `true` | – | 是否模态（背景遮罩 + 阻止外部交互）。 |
+
+## 示例
+
+### Sizes
+
+四档尺寸 — sm / md / lg / xl，对应 cloud-design 的 mini / small / medium / large。
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  {(['sm', 'md', 'lg', 'xl'] as const).map((size) => (
+    <Dialog key={size}>
+      <DialogTrigger asChild>
+        <Button variant="outline">size = {size}</Button>
+      </DialogTrigger>
+      <DialogContent size={size}>
+        <DialogHeader>
+          <DialogTitle>尺寸 {size}</DialogTitle>
+        </DialogHeader>
+        <DialogBody>当前 size={size}，在 sm 断点以上生效。</DialogBody>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button variant="outline">取消</Button>
+          </DialogClose>
+          <Button>确定</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  ))}
+</div>
+```
+
+### WithExtra
+
+标题右侧附加内容 — 通过 DialogHeaderExtra 放置帮助链接 / 次要操作。
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>打开</Button>
+  </DialogTrigger>
+  <DialogContent size="md">
+    <DialogHeader>
+      <DialogTitle>新建安全组</DialogTitle>
+      <DialogHeaderExtra>
+        <a
+          href="#"
+          className="text-primary hover:text-primary/80"
+          onClick={(e) => e.preventDefault()}
+        >
+          如何创建安全组
+        </a>
+      </DialogHeaderExtra>
+      <DialogDescription>
+        安全组用于控制实例的入站和出站流量，创建后可在管理页面修改规则。
+      </DialogDescription>
+    </DialogHeader>
+    <DialogBody>
+      <div className="flex flex-col gap-3">
+        <div className="flex flex-col gap-1.5">
+          <Label>名称</Label>
+          <Input placeholder="请输入安全组名称" />
+        </div>
+      </div>
+    </DialogBody>
+    <DialogFooter>
+      <DialogClose asChild>
+        <Button variant="outline">取消</Button>
+      </DialogClose>
+      <Button>创建</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### CustomFooter
+
+自定义底部 — 通过 children 完全自定义按钮组合。
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>打开</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>发布订单</DialogTitle>
+    </DialogHeader>
+    <DialogFooter className="sm:justify-between">
+      <Button variant="ghost">保存草稿</Button>
+      <div className="flex gap-2">
+        <DialogClose asChild>
+          <Button variant="outline">取消</Button>
+        </DialogClose>
+        <Button variant="destructive">确认发布</Button>
+      </div>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### LargeContent
+
+大量内容 — Body 自带滚动，Footer 固定底部。
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>打开</Button>
+  </DialogTrigger>
+  <DialogContent
+    size="md"
+    // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- demo only: cap dialog height to 80vh to demonstrate scroll behavior.
+    className="max-h-[80vh] grid-rows-[auto_1fr_auto]"
+  >
+    <DialogHeader>
+      <DialogTitle>服务条款</DialogTitle>
+    </DialogHeader>
+    <DialogBody className="overflow-y-auto">
+      <div className="flex flex-col gap-2">
+        {Array.from({ length: 30 }).map((_, i) => (
+          <p key={i}>
+            {i + 1}. 用户应当遵守相关法律法规，不得利用本服务从事违法活动。
+          </p>
+        ))}
+      </div>
+    </DialogBody>
+    <DialogFooter>
+      <DialogClose asChild>
+        <Button variant="outline">取消</Button>
+      </DialogClose>
+      <Button>同意并继续</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### NoCloseButton
+
+隐藏关闭按钮 — 强制通过底部操作关闭，常用于流程类强引导。
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>打开</Button>
+  </DialogTrigger>
+  <DialogContent showCloseButton={false}>
+    <DialogHeader>
+      <DialogTitle>提示</DialogTitle>
+    </DialogHeader>
+    <DialogFooter>
+      <DialogClose asChild>
+        <Button>知道了</Button>
+      </DialogClose>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### Fullscreen
+
+全屏对话框 — 通过 className 覆盖实现全屏效果，适用于沉浸式编辑、大型表格预览等场景。
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>全屏打开</Button>
+  </DialogTrigger>
+  <DialogContent className="inset-0 top-0 left-0 max-w-none -translate-x-0 -translate-y-0 grid-rows-[auto_1fr_auto] rounded-none data-[state=open]:zoom-in-100 data-[state=open]:slide-in-from-bottom-2 data-[state=closed]:zoom-out-100 data-[state=closed]:slide-out-to-bottom-2 sm:max-w-none">
+    <DialogHeader>
+      <DialogTitle>全屏编辑</DialogTitle>
+    </DialogHeader>
+    <DialogBody className="overflow-y-auto">
+      这里是全屏内容区域，可放置大型表格、沉浸式表单等内容。
+    </DialogBody>
+    <DialogFooter>
+      <DialogClose asChild>
+        <Button variant="outline">取消</Button>
+      </DialogClose>
+      <Button>保存</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+### Accessibility
+
+无障碍 — autoFocus + aria-label，使屏幕阅读器能正确读取。
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>打开</Button>
+  </DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>欢迎使用</DialogTitle>
+    </DialogHeader>
+    <DialogBody>
+      <p tabIndex={0}>对话框打开时焦点会自动陷阱在内部，按 ESC 可退出。</p>
+    </DialogBody>
+    <DialogFooter>
+      <DialogClose asChild>
+        <Button variant="outline" aria-label="cancel">
+          取消
+        </Button>
+      </DialogClose>
+      <Button aria-label="ok" autoFocus>
+        确定
+      </Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```

package/src/components/dialog/stories.tsx

@@ -0,0 +1,330 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import * as React from 'react';
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogHeaderExtra,
+  DialogTitle,
+  DialogTrigger,
+} from './index';
+import { Button } from '@/components/button';
+import { Input } from '@/components/input';
+import { Label } from '@/components/label';
+
+const meta = {
+  title: '反馈 · Feedback/Dialog 对话框',
+  component: Dialog,
+  subcomponents: {
+    DialogContent,
+    DialogHeader,
+    DialogHeaderExtra,
+    DialogTitle,
+    DialogDescription,
+    DialogBody,
+    DialogFooter,
+    DialogClose,
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Dialog>;
+
+export default meta;
+type Story = StoryObj<typeof Dialog>;
+
+/** 基础对话框 — 表单编辑场景。 */
+export const Default: Story = {
+  render: () => (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button>打开</Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>编辑个人信息</DialogTitle>
+        </DialogHeader>
+        <DialogBody>
+          <div className="flex flex-col gap-3">
+            <div className="flex flex-col gap-1.5">
+              <Label>名称</Label>
+              <Input defaultValue="张三" />
+            </div>
+            <div className="flex flex-col gap-1.5">
+              <Label>邮箱</Label>
+              <Input defaultValue="zhangsan@example.com" />
+            </div>
+          </div>
+        </DialogBody>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button variant="outline">取消</Button>
+          </DialogClose>
+          <Button>保存</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  ),
+};
+
+/** 四档尺寸 — sm / md / lg / xl，对应 cloud-design 的 mini / small / medium / large。 */
+export const Sizes: Story = {
+  name: '尺寸 size',
+  render: () => (
+    <div className="flex flex-wrap gap-2">
+      {(['sm', 'md', 'lg', 'xl'] as const).map((size) => (
+        <Dialog key={size}>
+          <DialogTrigger asChild>
+            <Button variant="outline">size = {size}</Button>
+          </DialogTrigger>
+          <DialogContent size={size}>
+            <DialogHeader>
+              <DialogTitle>尺寸 {size}</DialogTitle>
+            </DialogHeader>
+            <DialogBody>当前 size={size}，在 sm 断点以上生效。</DialogBody>
+            <DialogFooter>
+              <DialogClose asChild>
+                <Button variant="outline">取消</Button>
+              </DialogClose>
+              <Button>确定</Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+      ))}
+    </div>
+  ),
+};
+
+/** 标题右侧附加内容 — 通过 DialogHeaderExtra 放置帮助链接 / 次要操作。 */
+export const WithExtra: Story = {
+  name: 'Header 附加内容',
+  render: () => (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button>打开</Button>
+      </DialogTrigger>
+      <DialogContent size="md">
+        <DialogHeader>
+          <DialogTitle>新建安全组</DialogTitle>
+          <DialogHeaderExtra>
+            <a
+              href="#"
+              className="text-primary hover:text-primary/80"
+              onClick={(e) => e.preventDefault()}
+            >
+              如何创建安全组
+            </a>
+          </DialogHeaderExtra>
+          <DialogDescription>
+            安全组用于控制实例的入站和出站流量，创建后可在管理页面修改规则。
+          </DialogDescription>
+        </DialogHeader>
+        <DialogBody>
+          <div className="flex flex-col gap-3">
+            <div className="flex flex-col gap-1.5">
+              <Label>名称</Label>
+              <Input placeholder="请输入安全组名称" />
+            </div>
+          </div>
+        </DialogBody>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button variant="outline">取消</Button>
+          </DialogClose>
+          <Button>创建</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  ),
+};
+
+/** 自定义底部 — 通过 children 完全自定义按钮组合。 */
+export const CustomFooter: Story = {
+  name: '自定义底部',
+  render: () => (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button>打开</Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>发布订单</DialogTitle>
+        </DialogHeader>
+        <DialogFooter className="sm:justify-between">
+          <Button variant="ghost">保存草稿</Button>
+          <div className="flex gap-2">
+            <DialogClose asChild>
+              <Button variant="outline">取消</Button>
+            </DialogClose>
+            <Button variant="destructive">确认发布</Button>
+          </div>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  ),
+};
+
+/** 大量内容 — Body 自带滚动，Footer 固定底部。 */
+export const LargeContent: Story = {
+  name: '滚动内容',
+  render: () => (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button>打开</Button>
+      </DialogTrigger>
+      <DialogContent
+        size="md"
+        // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- demo only: cap dialog height to 80vh to demonstrate scroll behavior.
+        className="max-h-[80vh] grid-rows-[auto_1fr_auto]"
+      >
+        <DialogHeader>
+          <DialogTitle>服务条款</DialogTitle>
+        </DialogHeader>
+        <DialogBody className="overflow-y-auto">
+          <div className="flex flex-col gap-2">
+            {Array.from({ length: 30 }).map((_, i) => (
+              <p key={i}>
+                {i + 1}. 用户应当遵守相关法律法规，不得利用本服务从事违法活动。
+              </p>
+            ))}
+          </div>
+        </DialogBody>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button variant="outline">取消</Button>
+          </DialogClose>
+          <Button>同意并继续</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  ),
+};
+
+/** 异步提交 — onSubmit 返回 Promise，按钮 loading 期间禁止关闭。 */
+export const AsyncSubmit: Story = {
+  name: '异步提交',
+  render: () => {
+    function Demo() {
+      const [open, setOpen] = React.useState(false);
+      const [loading, setLoading] = React.useState(false);
+      const onConfirm = async () => {
+        setLoading(true);
+        await new Promise((r) => setTimeout(r, 1500));
+        setLoading(false);
+        setOpen(false);
+      };
+      return (
+        <Dialog
+          open={open}
+          onOpenChange={(next) => {
+            if (loading) return;
+            setOpen(next);
+          }}
+        >
+          <DialogTrigger asChild>
+            <Button>打开</Button>
+          </DialogTrigger>
+          <DialogContent
+            onPointerDownOutside={(e) => loading && e.preventDefault()}
+            onEscapeKeyDown={(e) => loading && e.preventDefault()}
+          >
+            <DialogHeader>
+              <DialogTitle>确认删除？</DialogTitle>
+            </DialogHeader>
+            <DialogFooter>
+              <DialogClose asChild>
+                <Button variant="outline" disabled={loading}>
+                  取消
+                </Button>
+              </DialogClose>
+              <Button loading={loading} onClick={onConfirm}>
+                确认
+              </Button>
+            </DialogFooter>
+          </DialogContent>
+        </Dialog>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+/** 隐藏关闭按钮 — 强制通过底部操作关闭，常用于流程类强引导。 */
+export const NoCloseButton: Story = {
+  name: '无关闭按钮',
+  render: () => (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button>打开</Button>
+      </DialogTrigger>
+      <DialogContent showCloseButton={false}>
+        <DialogHeader>
+          <DialogTitle>提示</DialogTitle>
+        </DialogHeader>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button>知道了</Button>
+          </DialogClose>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  ),
+};
+
+/** 全屏对话框 — 通过 className 覆盖实现全屏效果，适用于沉浸式编辑、大型表格预览等场景。 */
+export const Fullscreen: Story = {
+  name: '全屏 Dialog',
+  render: () => (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button>全屏打开</Button>
+      </DialogTrigger>
+      <DialogContent className="inset-0 top-0 left-0 max-w-none -translate-x-0 -translate-y-0 grid-rows-[auto_1fr_auto] rounded-none data-[state=open]:zoom-in-100 data-[state=open]:slide-in-from-bottom-2 data-[state=closed]:zoom-out-100 data-[state=closed]:slide-out-to-bottom-2 sm:max-w-none">
+        <DialogHeader>
+          <DialogTitle>全屏编辑</DialogTitle>
+        </DialogHeader>
+        <DialogBody className="overflow-y-auto">
+          这里是全屏内容区域，可放置大型表格、沉浸式表单等内容。
+        </DialogBody>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button variant="outline">取消</Button>
+          </DialogClose>
+          <Button>保存</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  ),
+};
+
+/** 无障碍 — autoFocus + aria-label，使屏幕阅读器能正确读取。 */
+export const Accessibility: Story = {
+  name: '无障碍',
+  render: () => (
+    <Dialog>
+      <DialogTrigger asChild>
+        <Button>打开</Button>
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>欢迎使用</DialogTitle>
+        </DialogHeader>
+        <DialogBody>
+          <p tabIndex={0}>对话框打开时焦点会自动陷阱在内部，按 ESC 可退出。</p>
+        </DialogBody>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button variant="outline" aria-label="cancel">
+              取消
+            </Button>
+          </DialogClose>
+          <Button aria-label="ok" autoFocus>
+            确定
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  ),
+};