@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/sheet/meta.md

@@ -0,0 +1,226 @@
+# Sheet
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+抽屉 Sheet
+从屏幕边缘滑出的面板，承载详情、表单、筛选、二级流程等补充内容，基于 Radix Dialog 原语。
+采用 shadcn v4 composable 模式：所有结构以子组件显式拼装，方向通过 `side`（4 向）驱动，
+尺寸通过 `data-size` 驱动（参考 cloud-design Drawer 的 mini/small/medium/large）。
+视觉规范（与 Dialog 对齐）：
+- Header 区：`pt-3 pr-5 pb-3 pl-5`，底部 1px 分隔线 `border-border`，存在 SheetHeaderExtra 时动态加 `pr-14` 预留关闭按钮
+- Body 区：`px-5 pt-4 pb-5`，默认字号 14px、颜色 muted-foreground，自带垂直滚动
+- Footer 区：`px-4 py-2.5`，顶部分隔线默认透明（消费侧需要时设为 `border-t border-border`）
+- 关闭按钮：`absolute top-3 right-5`，可点击区 20px
+- 阴影：组件级 token `--drawer-shadow`，fallback `0px 0px 24px 0px rgba(0,0,0,0.1)`
+- 不设边框：抽屉与背景的边界由阴影表达，默认不画 border
+
+## 使用场景
+
+- 详情侧栏 / 多步流程的右侧面板
+- 大型筛选 / 配置编辑（避免 Dialog 高度受限）
+- 移动端导航或全屏操作菜单
+- 表单内容超出一屏需独立滚动的场景
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | – | – | 受控显示状态。 |
+| `defaultOpen` | `boolean` | `false` | – | 非受控初始显示状态。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 显示 / 关闭状态变化回调。 |
+| `modal` | `boolean` | `true` | – | 是否模态（背景遮罩 + 阻止外部交互）。 |
+
+## 示例
+
+### Sizes
+
+四档尺寸 — sm/md/lg/xl，对齐 cloud-design Drawer mini/small/medium/large。
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  {(['sm', 'md', 'lg', 'xl'] as const).map((size) => (
+    <Sheet key={size}>
+      <SheetTrigger asChild>
+        <Button variant="outline">size = {size}</Button>
+      </SheetTrigger>
+      <SheetContent size={size}>
+        <SheetHeader>
+          <SheetTitle>尺寸 {size}</SheetTitle>
+          <SheetDescription>
+            当前 size={size}，sm 断点以上限制最大宽度。
+          </SheetDescription>
+        </SheetHeader>
+        <SheetBody>
+          <p>用于横向对比四档宽度差异。</p>
+        </SheetBody>
+        <SheetFooter>
+          <SheetClose asChild>
+            <Button variant="outline">关闭</Button>
+          </SheetClose>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  ))}
+</div>
+```
+
+### WithExtra
+
+Header 附加内容 — 通过 SheetHeaderExtra 放置帮助链接 / 次要操作。
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild>
+    <Button>打开</Button>
+  </SheetTrigger>
+  <SheetContent size="md">
+    <SheetHeader>
+      <SheetTitle>新建安全组</SheetTitle>
+      <SheetHeaderExtra>
+        <a
+          href="#"
+          className="text-primary hover:text-primary/80"
+          onClick={(e) => e.preventDefault()}
+        >
+          如何创建安全组
+        </a>
+      </SheetHeaderExtra>
+      <SheetDescription>
+        安全组用于控制实例的入站和出站流量，创建后可在管理页面修改规则。
+      </SheetDescription>
+    </SheetHeader>
+    <SheetBody>
+      <div className="flex flex-col gap-3">
+        <div className="flex flex-col gap-1.5">
+          <Label>名称</Label>
+          <Input placeholder="请输入安全组名称" />
+        </div>
+      </div>
+    </SheetBody>
+    <SheetFooter>
+      <Button>创建</Button>
+      <SheetClose asChild>
+        <Button variant="outline">取消</Button>
+      </SheetClose>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+### WithFooter
+
+标准底部按钮 — 取消 + 确定，对应 cloud-design Drawer 的 onOk/onCancel 默认形态。
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild>
+    <Button>打开具有确定和关闭操作的 Sheet</Button>
+  </SheetTrigger>
+  <SheetContent size="md">
+    <SheetHeader>
+      <SheetTitle>具有确定和关闭操作的 Sheet</SheetTitle>
+    </SheetHeader>
+    <SheetBody>
+      <p>具有确定和关闭操作的 Sheet。</p>
+    </SheetBody>
+    <SheetFooter>
+      <SheetClose asChild>
+        <Button>确定</Button>
+      </SheetClose>
+      <SheetClose asChild>
+        <Button variant="outline">取消</Button>
+      </SheetClose>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+### CustomFooter
+
+自定义底部 — 三按钮 + 顶部分隔线 + 左对齐，对应 cloud-design Drawer 的 customFooter demo。
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild>
+    <Button>打开完全自定义 footer 的 Sheet</Button>
+  </SheetTrigger>
+  <SheetContent size="sm">
+    <SheetHeader>
+      <SheetTitle>完全自定义 footer 的 Sheet</SheetTitle>
+    </SheetHeader>
+    <SheetBody>
+      <p>完全自定义 footer 的 Sheet。</p>
+    </SheetBody>
+    <SheetFooter className="border-border">
+      <SheetClose asChild>
+        <Button>确定</Button>
+      </SheetClose>
+      <Button variant="secondary">这是一个自定义的按钮</Button>
+      <SheetClose asChild>
+        <Button variant="outline">取消</Button>
+      </SheetClose>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+### LargeContent
+
+大量内容 — Body 自带滚动，Footer 固定底部。
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild>
+    <Button>打开信息超过一屏的 Sheet</Button>
+  </SheetTrigger>
+  <SheetContent size="md">
+    <SheetHeader>
+      <SheetTitle>信息超过一屏的 Sheet</SheetTitle>
+    </SheetHeader>
+    <SheetBody>
+      <div className="flex flex-col gap-2">
+        {Array.from({ length: 60 }).map((_, i) => (
+          <p key={i}>{i + 1}. 信息超过一屏的 Sheet</p>
+        ))}
+        <p>Sheet 的底部</p>
+      </div>
+    </SheetBody>
+    <SheetFooter className="border-border">
+      <SheetClose asChild>
+        <Button>确定</Button>
+      </SheetClose>
+      <SheetClose asChild>
+        <Button variant="outline">取消</Button>
+      </SheetClose>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+### NoCloseButton
+
+隐藏关闭按钮 — 强制通过底部操作关闭，常用于流程类强引导。
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild>
+    <Button>打开</Button>
+  </SheetTrigger>
+  <SheetContent showCloseButton={false}>
+    <SheetHeader>
+      <SheetTitle>提示</SheetTitle>
+      <SheetDescription>请通过底部按钮完成下一步操作。</SheetDescription>
+    </SheetHeader>
+    <SheetBody>
+      <p>这里是提示内容。</p>
+    </SheetBody>
+    <SheetFooter>
+      <SheetClose asChild>
+        <Button>知道了</Button>
+      </SheetClose>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```

package/src/components/sheet/stories.tsx

@@ -0,0 +1,405 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import * as React from 'react';
+import {
+  Sheet,
+  SheetBody,
+  SheetClose,
+  SheetContent,
+  SheetDescription,
+  SheetFooter,
+  SheetHeader,
+  SheetHeaderExtra,
+  SheetTitle,
+  SheetTrigger,
+} from './index';
+import { Button } from '@/components/button';
+import { Input } from '@/components/input';
+import { Label } from '@/components/label';
+import { RadioGroup, RadioGroupItem } from '@/components/radio-group';
+
+const meta = {
+  title: '反馈 · Feedback/Sheet 抽屉',
+  component: Sheet,
+  subcomponents: {
+    SheetContent,
+    SheetHeader,
+    SheetHeaderExtra,
+    SheetTitle,
+    SheetDescription,
+    SheetBody,
+    SheetFooter,
+    SheetClose,
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Sheet>;
+
+export default meta;
+type Story = StoryObj<typeof Sheet>;
+
+/** 基础抽屉 — 默认右侧滑出，标准 Header / Body / Footer 拼装。 */
+export const Default: Story = {
+  render: () => (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button>打开</Button>
+      </SheetTrigger>
+      <SheetContent>
+        <SheetHeader>
+          <SheetTitle>编辑配置</SheetTitle>
+          <SheetDescription>在此修改项目配置信息。</SheetDescription>
+        </SheetHeader>
+        <SheetBody>
+          <div className="flex flex-col gap-3">
+            <div className="flex flex-col gap-1.5">
+              <Label>项目名称</Label>
+              <Input defaultValue="my-project" />
+            </div>
+            <div className="flex flex-col gap-1.5">
+              <Label>描述</Label>
+              <Input placeholder="可选" />
+            </div>
+          </div>
+        </SheetBody>
+        <SheetFooter>
+          <Button>保存</Button>
+          <SheetClose asChild>
+            <Button variant="outline">取消</Button>
+          </SheetClose>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  ),
+};
+
+/** 四档尺寸 — sm/md/lg/xl，对齐 cloud-design Drawer 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) => (
+        <Sheet key={size}>
+          <SheetTrigger asChild>
+            <Button variant="outline">size = {size}</Button>
+          </SheetTrigger>
+          <SheetContent size={size}>
+            <SheetHeader>
+              <SheetTitle>尺寸 {size}</SheetTitle>
+              <SheetDescription>
+                当前 size={size}，sm 断点以上限制最大宽度。
+              </SheetDescription>
+            </SheetHeader>
+            <SheetBody>
+              <p>用于横向对比四档宽度差异。</p>
+            </SheetBody>
+            <SheetFooter>
+              <SheetClose asChild>
+                <Button variant="outline">关闭</Button>
+              </SheetClose>
+            </SheetFooter>
+          </SheetContent>
+        </Sheet>
+      ))}
+    </div>
+  ),
+};
+
+/** 自定义弹出方向 — 4 向 side 切换。 */
+export const Placement: Story = {
+  name: '弹出方向 side',
+  render: () => {
+    function Demo() {
+      const [side, setSide] = React.useState<
+        'top' | 'right' | 'bottom' | 'left'
+      >('right');
+      return (
+        <div className="flex flex-col gap-3">
+          <RadioGroup
+            value={side}
+            onValueChange={(v) => setSide(v as typeof side)}
+            className="flex flex-row gap-4"
+          >
+            {(['right', 'bottom', 'left', 'top'] as const).map((p) => (
+              <div key={p} className="flex items-center gap-1.5">
+                <RadioGroupItem value={p} id={`side-${p}`} />
+                <Label htmlFor={`side-${p}`}>{p}</Label>
+              </div>
+            ))}
+          </RadioGroup>
+          <Sheet>
+            <SheetTrigger asChild>
+              <Button>打开 {side} 方向</Button>
+            </SheetTrigger>
+            <SheetContent side={side}>
+              <SheetHeader>
+                <SheetTitle>标题</SheetTitle>
+              </SheetHeader>
+              <SheetBody>
+                Start your business here by searching a popular product
+              </SheetBody>
+            </SheetContent>
+          </Sheet>
+        </div>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+/** Header 附加内容 — 通过 SheetHeaderExtra 放置帮助链接 / 次要操作。 */
+export const WithExtra: Story = {
+  name: 'Header 附加内容',
+  render: () => (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button>打开</Button>
+      </SheetTrigger>
+      <SheetContent size="md">
+        <SheetHeader>
+          <SheetTitle>新建安全组</SheetTitle>
+          <SheetHeaderExtra>
+            <a
+              href="#"
+              className="text-primary hover:text-primary/80"
+              onClick={(e) => e.preventDefault()}
+            >
+              如何创建安全组
+            </a>
+          </SheetHeaderExtra>
+          <SheetDescription>
+            安全组用于控制实例的入站和出站流量，创建后可在管理页面修改规则。
+          </SheetDescription>
+        </SheetHeader>
+        <SheetBody>
+          <div className="flex flex-col gap-3">
+            <div className="flex flex-col gap-1.5">
+              <Label>名称</Label>
+              <Input placeholder="请输入安全组名称" />
+            </div>
+          </div>
+        </SheetBody>
+        <SheetFooter>
+          <Button>创建</Button>
+          <SheetClose asChild>
+            <Button variant="outline">取消</Button>
+          </SheetClose>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  ),
+};
+
+/** 标准底部按钮 — 取消 + 确定，对应 cloud-design Drawer 的 onOk/onCancel 默认形态。 */
+export const WithFooter: Story = {
+  name: '标准底部',
+  render: () => (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button>打开具有确定和关闭操作的 Sheet</Button>
+      </SheetTrigger>
+      <SheetContent size="md">
+        <SheetHeader>
+          <SheetTitle>具有确定和关闭操作的 Sheet</SheetTitle>
+        </SheetHeader>
+        <SheetBody>
+          <p>具有确定和关闭操作的 Sheet。</p>
+        </SheetBody>
+        <SheetFooter>
+          <SheetClose asChild>
+            <Button>确定</Button>
+          </SheetClose>
+          <SheetClose asChild>
+            <Button variant="outline">取消</Button>
+          </SheetClose>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  ),
+};
+
+/** 自定义底部 — 三按钮 + 顶部分隔线 + 左对齐，对应 cloud-design Drawer 的 customFooter demo。 */
+export const CustomFooter: Story = {
+  name: '自定义底部',
+  render: () => (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button>打开完全自定义 footer 的 Sheet</Button>
+      </SheetTrigger>
+      <SheetContent size="sm">
+        <SheetHeader>
+          <SheetTitle>完全自定义 footer 的 Sheet</SheetTitle>
+        </SheetHeader>
+        <SheetBody>
+          <p>完全自定义 footer 的 Sheet。</p>
+        </SheetBody>
+        <SheetFooter className="border-border">
+          <SheetClose asChild>
+            <Button>确定</Button>
+          </SheetClose>
+          <Button variant="secondary">这是一个自定义的按钮</Button>
+          <SheetClose asChild>
+            <Button variant="outline">取消</Button>
+          </SheetClose>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  ),
+};
+
+/** 大量内容 — Body 自带滚动，Footer 固定底部。 */
+export const LargeContent: Story = {
+  name: '滚动内容',
+  render: () => (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button>打开信息超过一屏的 Sheet</Button>
+      </SheetTrigger>
+      <SheetContent size="md">
+        <SheetHeader>
+          <SheetTitle>信息超过一屏的 Sheet</SheetTitle>
+        </SheetHeader>
+        <SheetBody>
+          <div className="flex flex-col gap-2">
+            {Array.from({ length: 60 }).map((_, i) => (
+              <p key={i}>{i + 1}. 信息超过一屏的 Sheet</p>
+            ))}
+            <p>Sheet 的底部</p>
+          </div>
+        </SheetBody>
+        <SheetFooter className="border-border">
+          <SheetClose asChild>
+            <Button>确定</Button>
+          </SheetClose>
+          <SheetClose asChild>
+            <Button variant="outline">取消</Button>
+          </SheetClose>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  ),
+};
+
+/** 双层抽屉 — 抽屉内打开新的抽屉，对应 cloud-design Drawer 的 double demo。 */
+export const Nested: Story = {
+  name: '双层抽屉',
+  render: () => {
+    function Demo() {
+      const [outer, setOuter] = React.useState(false);
+      const [inner, setInner] = React.useState(false);
+      return (
+        <>
+          <Button onClick={() => setOuter(true)}>Open drawer</Button>
+          <Sheet open={outer} onOpenChange={setOuter}>
+            <SheetContent size="md">
+              <SheetHeader>
+                <SheetTitle>Multi-level drawer</SheetTitle>
+              </SheetHeader>
+              <SheetBody>
+                <Button onClick={() => setInner(true)}>Two-level drawer</Button>
+                <div className="mt-10 flex flex-col gap-2">
+                  {Array.from({ length: 20 }).map((_, i) => (
+                    <p key={i}>很长的内容 {i + 1}</p>
+                  ))}
+                  <p>底部的内容</p>
+                </div>
+              </SheetBody>
+              <SheetFooter className="border-border">
+                <Button onClick={() => setOuter(false)}>Submit</Button>
+                <Button variant="outline" onClick={() => setOuter(false)}>
+                  Cancel
+                </Button>
+              </SheetFooter>
+              <Sheet open={inner} onOpenChange={setInner}>
+                <SheetContent size="sm">
+                  <SheetHeader>
+                    <SheetTitle>Two-level Drawer</SheetTitle>
+                  </SheetHeader>
+                  <SheetBody>This is two-level drawer</SheetBody>
+                </SheetContent>
+              </Sheet>
+            </SheetContent>
+          </Sheet>
+        </>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+/** 受控异步关闭 — onOpenChange 在 loading 期间拦截关闭，按钮 loading 期间禁止外部交互。 */
+export const Controlled: 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 (
+        <Sheet
+          open={open}
+          onOpenChange={(next) => {
+            if (loading) return;
+            setOpen(next);
+          }}
+        >
+          <SheetTrigger asChild>
+            <Button>打开</Button>
+          </SheetTrigger>
+          <SheetContent
+            size="sm"
+            onPointerDownOutside={(e) => loading && e.preventDefault()}
+            onEscapeKeyDown={(e) => loading && e.preventDefault()}
+          >
+            <SheetHeader>
+              <SheetTitle>确认提交？</SheetTitle>
+            </SheetHeader>
+            <SheetBody>
+              <p>提交期间无法点击遮罩或按 ESC 关闭。</p>
+            </SheetBody>
+            <SheetFooter>
+              <Button loading={loading} onClick={onConfirm}>
+                确认
+              </Button>
+              <SheetClose asChild>
+                <Button variant="outline" disabled={loading}>
+                  取消
+                </Button>
+              </SheetClose>
+            </SheetFooter>
+          </SheetContent>
+        </Sheet>
+      );
+    }
+    return <Demo />;
+  },
+};
+
+/** 隐藏关闭按钮 — 强制通过底部操作关闭，常用于流程类强引导。 */
+export const NoCloseButton: Story = {
+  name: '无关闭按钮',
+  render: () => (
+    <Sheet>
+      <SheetTrigger asChild>
+        <Button>打开</Button>
+      </SheetTrigger>
+      <SheetContent showCloseButton={false}>
+        <SheetHeader>
+          <SheetTitle>提示</SheetTitle>
+          <SheetDescription>请通过底部按钮完成下一步操作。</SheetDescription>
+        </SheetHeader>
+        <SheetBody>
+          <p>这里是提示内容。</p>
+        </SheetBody>
+        <SheetFooter>
+          <SheetClose asChild>
+            <Button>知道了</Button>
+          </SheetClose>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  ),
+};