@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/navigation-menu/meta.md

@@ -0,0 +1,66 @@
+# NavigationMenu
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+导航菜单 NavigationMenu
+水平导航栏，支持嵌套菜单、多列布局和快捷链接展示。
+
+## 使用场景
+
+- 网站/管理后台顶部导航栏
+- 需要下拉菜单展示子导航项时
+- 配合 Menubar 或独立使用
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | – | – | 受控当前激活的菜单项值。 |
+| `defaultValue` | `string` | – | – | 非受控初始激活的菜单项值。 |
+| `onValueChange` | `(value: string) => void` | – | – | 菜单项切换回调。 |
+| `dir` | `'ltr' \| 'rtl'` | – | – | 文字方向。 |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | – | 菜单方向。 |
+| `delayDuration` | `number` | `200` | – | 悬停多久后打开（毫秒）。 |
+| `skipDelayDuration` | `number` | `300` | – | 从一个菜单跳到另一个菜单时跳过开启延迟的间隔（毫秒）。 |
+| `viewport` | `boolean` | `true` | – | 是否启用 Viewport 子菜单容器。 |
+
+## 示例
+
+### WithoutViewport
+
+无 viewport 模式，弹层直接跟随触发器。
+
+```tsx
+<div className="min-h-72 pb-48">
+  <NavigationMenu viewport={false}>
+    <NavigationMenuList>
+      <NavigationMenuItem>
+        <NavigationMenuTrigger>产品</NavigationMenuTrigger>
+        <NavigationMenuContent>
+          <div className="grid w-64 gap-1 p-2">
+            <NavigationMenuLink href="#">
+              <span className="text-xs">云计算</span>
+            </NavigationMenuLink>
+            <NavigationMenuLink href="#">
+              <span className="text-xs">数据库</span>
+            </NavigationMenuLink>
+            <NavigationMenuLink href="#">
+              <span className="text-xs">中间件</span>
+            </NavigationMenuLink>
+          </div>
+        </NavigationMenuContent>
+      </NavigationMenuItem>
+      <NavigationMenuItem>
+        <NavigationMenuLink
+          href="#"
+          className={navigationMenuTriggerStyle()}
+        >
+          定价
+        </NavigationMenuLink>
+      </NavigationMenuItem>
+    </NavigationMenuList>
+  </NavigationMenu>
+</div>
+```

package/src/components/navigation-menu/stories.tsx

@@ -0,0 +1,137 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  NavigationMenu,
+  NavigationMenuList,
+  NavigationMenuItem,
+  NavigationMenuTrigger,
+  NavigationMenuContent,
+  NavigationMenuLink,
+  navigationMenuTriggerStyle,
+} from './index';
+
+const meta: Meta<typeof NavigationMenu> = {
+  title: '导航 · Navigation/NavigationMenu 导航菜单',
+  component: NavigationMenu,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 带下拉面板的导航菜单，适用于站点顶部导航。 */
+export const Default: Story = {
+  render: () => (
+    <div className="min-h-96 pb-72">
+      <NavigationMenu>
+        <NavigationMenuList>
+          <NavigationMenuItem>
+            <NavigationMenuTrigger>快速开始</NavigationMenuTrigger>
+            <NavigationMenuContent>
+              <div className="grid w-96 gap-2 p-3">
+                <NavigationMenuLink href="#">
+                  <div className="flex flex-col gap-1">
+                    <span className="text-xs font-medium">安装指南</span>
+                    <span className="text-xs text-muted-foreground">
+                      如何在项目中集成组件库。
+                    </span>
+                  </div>
+                </NavigationMenuLink>
+                <NavigationMenuLink href="#">
+                  <div className="flex flex-col gap-1">
+                    <span className="text-xs font-medium">主题配置</span>
+                    <span className="text-xs text-muted-foreground">
+                      通过 design token 自定义主题。
+                    </span>
+                  </div>
+                </NavigationMenuLink>
+              </div>
+            </NavigationMenuContent>
+          </NavigationMenuItem>
+          <NavigationMenuItem>
+            <NavigationMenuTrigger>组件</NavigationMenuTrigger>
+            <NavigationMenuContent>
+              <div className="grid w-96 grid-cols-2 gap-2 p-3">
+                <NavigationMenuLink href="#">
+                  <div className="flex flex-col gap-1">
+                    <span className="text-xs font-medium">Button 按钮</span>
+                    <span className="text-xs text-muted-foreground">
+                      触发操作或事件。
+                    </span>
+                  </div>
+                </NavigationMenuLink>
+                <NavigationMenuLink href="#">
+                  <div className="flex flex-col gap-1">
+                    <span className="text-xs font-medium">Input 输入框</span>
+                    <span className="text-xs text-muted-foreground">
+                      接收用户文本输入。
+                    </span>
+                  </div>
+                </NavigationMenuLink>
+                <NavigationMenuLink href="#">
+                  <div className="flex flex-col gap-1">
+                    <span className="text-xs font-medium">Dialog 对话框</span>
+                    <span className="text-xs text-muted-foreground">
+                      模态对话窗口。
+                    </span>
+                  </div>
+                </NavigationMenuLink>
+                <NavigationMenuLink href="#">
+                  <div className="flex flex-col gap-1">
+                    <span className="text-xs font-medium">Table 表格</span>
+                    <span className="text-xs text-muted-foreground">
+                      展示结构化数据集。
+                    </span>
+                  </div>
+                </NavigationMenuLink>
+              </div>
+            </NavigationMenuContent>
+          </NavigationMenuItem>
+          <NavigationMenuItem>
+            <NavigationMenuLink
+              href="#"
+              className={navigationMenuTriggerStyle()}
+            >
+              文档
+            </NavigationMenuLink>
+          </NavigationMenuItem>
+        </NavigationMenuList>
+      </NavigationMenu>
+    </div>
+  ),
+};
+
+/** 无 viewport 模式，弹层直接跟随触发器。 */
+export const WithoutViewport: Story = {
+  render: () => (
+    <div className="min-h-72 pb-48">
+      <NavigationMenu viewport={false}>
+        <NavigationMenuList>
+          <NavigationMenuItem>
+            <NavigationMenuTrigger>产品</NavigationMenuTrigger>
+            <NavigationMenuContent>
+              <div className="grid w-64 gap-1 p-2">
+                <NavigationMenuLink href="#">
+                  <span className="text-xs">云计算</span>
+                </NavigationMenuLink>
+                <NavigationMenuLink href="#">
+                  <span className="text-xs">数据库</span>
+                </NavigationMenuLink>
+                <NavigationMenuLink href="#">
+                  <span className="text-xs">中间件</span>
+                </NavigationMenuLink>
+              </div>
+            </NavigationMenuContent>
+          </NavigationMenuItem>
+          <NavigationMenuItem>
+            <NavigationMenuLink
+              href="#"
+              className={navigationMenuTriggerStyle()}
+            >
+              定价
+            </NavigationMenuLink>
+          </NavigationMenuItem>
+        </NavigationMenuList>
+      </NavigationMenu>
+    </div>
+  ),
+};

package/src/components/page-header/index.tsx

@@ -0,0 +1,218 @@
+/**
+ * 页头 PageHeader
+ *
+ * 页面顶部区域，包含面包屑导航、标题、描述、操作按钮等信息。
+ *
+ * @when
+ * - 需要清晰展示页面标题与层级
+ * - 页面含返回按钮、操作按钮等顶部交互
+ * - 配合 Breadcrumb 展示路径导航
+ */
+
+import * as React from 'react';
+import { ArrowLeft, Info } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@/components/tooltip';
+
+// ─── PageHeader ─────────────────────────────────────────────────────────────
+
+/** 页头根容器。 */
+const PageHeader = React.forwardRef<
+  HTMLElement,
+  React.HTMLAttributes<HTMLElement>
+>(({ className, ...props }, ref) => (
+  <header
+    ref={ref}
+    data-slot="page-header"
+    className={cn('relative flex flex-col gap-2', className)}
+    {...props}
+  />
+));
+PageHeader.displayName = 'PageHeader';
+
+// ─── PageHeaderNav ──────────────────────────────────────────────────────────
+
+/** 导航层（面包屑 + 右侧链接）。 */
+const PageHeaderNav = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="page-header-nav"
+    className={cn(
+      'flex min-h-5 items-center justify-between text-xs',
+      className,
+    )}
+    {...props}
+  />
+));
+PageHeaderNav.displayName = 'PageHeaderNav';
+
+// ─── PageHeaderContent ──────────────────────────────────────────────────────
+
+/** 主内容区（左右双列布局）。 */
+const PageHeaderContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="page-header-content"
+    className={cn(
+      'flex flex-wrap items-start justify-between gap-4',
+      className,
+    )}
+    {...props}
+  />
+));
+PageHeaderContent.displayName = 'PageHeaderContent';
+
+// ─── PageHeaderHeading ──────────────────────────────────────────────────────
+
+export interface PageHeaderHeadingProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** 显示返回按钮。 @default false */
+  goBack?: boolean;
+  /** 返回按钮点击回调。 */
+  onBack?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+}
+
+/** 标题行（支持前置返回按钮）。 */
+const PageHeaderHeading = React.forwardRef<
+  HTMLDivElement,
+  PageHeaderHeadingProps
+>(({ className, goBack = false, onBack, children, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="page-header-heading"
+    className={cn('flex items-center gap-2', className)}
+    {...props}
+  >
+    {goBack && (
+      <button
+        type="button"
+        onClick={onBack}
+        aria-label="返回"
+        className={cn(
+          'inline-flex shrink-0 cursor-pointer items-center justify-center rounded-sm text-muted-foreground transition-colors',
+          'hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+        )}
+      >
+        <ArrowLeft className="size-6" aria-hidden="true" />
+      </button>
+    )}
+    {children}
+  </div>
+));
+PageHeaderHeading.displayName = 'PageHeaderHeading';
+
+// ─── PageHeaderTitle ────────────────────────────────────────────────────────
+
+export interface PageHeaderTitleProps
+  extends React.HTMLAttributes<HTMLHeadingElement> {
+  /** 标题旁的信息提示内容。传入则在标题右侧渲染 ⓘ 图标 + Tooltip。 */
+  tooltip?: React.ReactNode;
+}
+
+/** 标题文字（h2，对齐 Typography level=2，可选 ⓘ 提示）。 */
+const PageHeaderTitle = React.forwardRef<
+  HTMLHeadingElement,
+  PageHeaderTitleProps
+>(({ className, children, tooltip, ...props }, ref) => (
+  <h2
+    ref={ref}
+    data-slot="page-header-title"
+    className={cn(
+      'inline-flex items-center gap-1 text-2xl font-semibold tracking-tight',
+      className,
+    )}
+    {...props}
+  >
+    {children}
+    {tooltip != null && (
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              aria-label="详细信息"
+              className="inline-flex cursor-help items-center text-xs font-normal text-muted-foreground transition-colors hover:text-foreground"
+            >
+              <Info className="size-4" aria-hidden="true" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent>{tooltip}</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+    )}
+  </h2>
+));
+PageHeaderTitle.displayName = 'PageHeaderTitle';
+
+// ─── PageHeaderDescription ──────────────────────────────────────────────────
+
+/** 描述文字。 */
+const PageHeaderDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    data-slot="page-header-description"
+    className={cn('my-2 text-xs text-muted-foreground', className)}
+    {...props}
+  />
+));
+PageHeaderDescription.displayName = 'PageHeaderDescription';
+
+// ─── PageHeaderActions ──────────────────────────────────────────────────────
+
+/** 操作按钮区。 */
+const PageHeaderActions = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="page-header-actions"
+    className={cn('flex shrink-0 items-center gap-2', className)}
+    {...props}
+  />
+));
+PageHeaderActions.displayName = 'PageHeaderActions';
+
+// ─── PageHeaderFooter ───────────────────────────────────────────────────────
+
+/** 底部区域（带顶部分隔线）。 */
+const PageHeaderFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    data-slot="page-header-footer"
+    className={cn('mt-2', className)}
+    {...props}
+  />
+));
+PageHeaderFooter.displayName = 'PageHeaderFooter';
+
+// ─── exports ────────────────────────────────────────────────────────────────
+
+export {
+  PageHeader,
+  PageHeaderNav,
+  PageHeaderContent,
+  PageHeaderHeading,
+  PageHeaderTitle,
+  PageHeaderDescription,
+  PageHeaderActions,
+  PageHeaderFooter,
+};

package/src/components/page-header/meta.md

@@ -0,0 +1,211 @@
+# PageHeaderHeading
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+页头 PageHeader
+页面顶部区域，包含面包屑导航、标题、描述、操作按钮等信息。
+
+## 使用场景
+
+- 需要清晰展示页面标题与层级
+- 页面含返回按钮、操作按钮等顶部交互
+- 配合 Breadcrumb 展示路径导航
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `goBack` | `boolean` | `false` | – | 显示返回按钮。 |
+| `onBack` | `(e: React.MouseEvent<HTMLButtonElement>) => void` | – | – | 返回按钮点击回调。 |
+| `tooltip` | `React.ReactNode` | – | – | 标题旁的信息提示内容。传入则在标题右侧渲染 ⓘ 图标 + Tooltip。 |
+
+## 示例
+
+### WithStatistic
+
+带数据概览：右侧使用 Statistic 组件展示 KPI 指标。
+
+```tsx
+<PageHeader>
+  <PageHeaderContent>
+    <div className="flex flex-col">
+      <PageHeaderHeading>
+        <PageHeaderTitle>页面标题</PageHeaderTitle>
+      </PageHeaderHeading>
+      <PageHeaderDescription>
+        页面描述页面描述页面描述页面描述页面描述页面描述页面描述
+      </PageHeaderDescription>
+    </div>
+    <div className="flex items-center gap-6">
+      <Statistic title="总数" value={456} valueClassName="text-base" />
+      <Statistic title="运行中" value={324} valueClassName="text-base" />
+      <Statistic title="已暂停" value={46} valueClassName="text-base" />
+      <Statistic
+        title="停止"
+        value={14}
+        valueClassName="text-base text-destructive"
+      />
+      <Statistic title="回收站" value={8} valueClassName="text-base" />
+    </div>
+  </PageHeaderContent>
+</PageHeader>
+```
+
+### WithDescriptions
+
+带描述列表：底部使用 Descriptions 组件展示项目详细信息。
+
+```tsx
+<PageHeader>
+  <PageHeaderContent>
+    <div className="flex flex-col">
+      <PageHeaderHeading>
+        <PageHeaderTitle>项目详情</PageHeaderTitle>
+      </PageHeaderHeading>
+      <PageHeaderDescription>
+        查看项目完整信息与最新状态。
+      </PageHeaderDescription>
+    </div>
+    <PageHeaderActions>
+      <Button variant="outline">普通按钮</Button>
+      <Button>主要按钮</Button>
+    </PageHeaderActions>
+  </PageHeaderContent>
+  <PageHeaderFooter>
+    <Descriptions column={3}>
+      <DescriptionsItem>
+        <DescriptionsLabel>项目名称</DescriptionsLabel>
+        <DescriptionsContent>Teamix Evo</DescriptionsContent>
+      </DescriptionsItem>
+      <DescriptionsItem>
+        <DescriptionsLabel>负责人</DescriptionsLabel>
+        <DescriptionsContent>张三</DescriptionsContent>
+      </DescriptionsItem>
+      <DescriptionsItem>
+        <DescriptionsLabel>状态</DescriptionsLabel>
+        <DescriptionsContent>进行中</DescriptionsContent>
+      </DescriptionsItem>
+      <DescriptionsItem>
+        <DescriptionsLabel>创建时间</DescriptionsLabel>
+        <DescriptionsContent>2024-01-01</DescriptionsContent>
+      </DescriptionsItem>
+      <DescriptionsItem>
+        <DescriptionsLabel>更新时间</DescriptionsLabel>
+        <DescriptionsContent>2024-06-01</DescriptionsContent>
+      </DescriptionsItem>
+      <DescriptionsItem>
+        <DescriptionsLabel>描述</DescriptionsLabel>
+        <DescriptionsContent>面向 AI Coding 的研发套件</DescriptionsContent>
+      </DescriptionsItem>
+    </Descriptions>
+  </PageHeaderFooter>
+</PageHeader>
+```
+
+### WithViewToggle
+
+带视图切换：标题旁使用 ToggleGroup 切换视图模式。
+
+```tsx
+<PageHeader>
+  <PageHeaderNav>
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">首页</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">二级标题</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">三级标题</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>当前</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  </PageHeaderNav>
+  <PageHeaderContent>
+    <PageHeaderHeading goBack onBack={() => alert('返回')}>
+      <PageHeaderTitle>页面标题</PageHeaderTitle>
+      <ToggleGroup type="single" defaultValue="list" spacing={0}>
+        <ToggleGroupItem value="card" aria-label="卡片视图">
+          <Layers className="size-4" />
+        </ToggleGroupItem>
+        <ToggleGroupItem value="list" aria-label="列表视图">
+          <List className="size-4" />
+        </ToggleGroupItem>
+        <ToggleGroupItem value="grid" aria-label="网格视图">
+          <LayoutGrid className="size-4" />
+        </ToggleGroupItem>
+      </ToggleGroup>
+    </PageHeaderHeading>
+  </PageHeaderContent>
+</PageHeader>
+```
+
+### WithBackgroundIllustration
+
+右侧装饰图版本：无操作按钮，右侧用 lucide icon（Cloud）放大 + 半透明作背景插画。
+
+```tsx
+<PageHeader>
+  <Cloud
+    aria-hidden="true"
+    className="pointer-events-none absolute top-0 right-0 size-24 text-primary/10"
+  />
+  <PageHeaderNav>
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">首页</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>云服务概览</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  </PageHeaderNav>
+  <PageHeaderContent>
+    <div className="flex flex-col">
+      <PageHeaderHeading>
+        <span
+          aria-hidden="true"
+          className="flex size-8 shrink-0 items-center justify-center rounded-md bg-primary text-primary-foreground"
+        >
+          <Boxes className="size-5" />
+        </span>
+        <PageHeaderTitle>云服务概览</PageHeaderTitle>
+      </PageHeaderHeading>
+      <PageHeaderDescription>
+        管理您的云资源、查看实例运行状态与计费明细。
+      </PageHeaderDescription>
+    </div>
+  </PageHeaderContent>
+</PageHeader>
+```
+
+### WithGoBack
+
+带返回按钮的详情页头。
+
+```tsx
+<PageHeader>
+  <PageHeaderContent>
+    <PageHeaderHeading goBack onBack={() => alert('返回')}>
+      <PageHeaderTitle>详情页标题</PageHeaderTitle>
+    </PageHeaderHeading>
+    <PageHeaderActions>
+      <Button>操作</Button>
+    </PageHeaderActions>
+  </PageHeaderContent>
+  <PageHeaderDescription>补充描述信息。</PageHeaderDescription>
+</PageHeader>
+```