@teamix-evo/ui 0.4.0 → 0.5.0

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

@@ -0,0 +1,290 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Boxes, BookOpen, Cloud, Layers, List, LayoutGrid } from 'lucide-react';
+import {
+  PageHeader,
+  PageHeaderNav,
+  PageHeaderContent,
+  PageHeaderHeading,
+  PageHeaderTitle,
+  PageHeaderDescription,
+  PageHeaderActions,
+  PageHeaderFooter,
+} from './index';
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbSeparator,
+  BreadcrumbPage,
+} from '@/components/breadcrumb';
+import { Button } from '@/components/button';
+import { Tag } from '@/components/tag';
+import { Statistic } from '@/components/statistic';
+import {
+  Descriptions,
+  DescriptionsContent,
+  DescriptionsItem,
+  DescriptionsLabel,
+} from '@/components/descriptions';
+import { ToggleGroup, ToggleGroupItem } from '@/components/toggle-group';
+import { Separator } from '@/components/separator';
+
+const meta: Meta<typeof PageHeader> = {
+  title: '导航 · Navigation/PageHeader 页头',
+  component: PageHeader,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 完整版页头：面包屑 + 帮助链接 + 返回 + 主图标 + 标题（含 ⓘ） + 描述 + 多操作 + 底部信息。 */
+export const Default: Story = {
+  render: () => (
+    <PageHeader>
+      <PageHeaderNav>
+        <Breadcrumb>
+          <BreadcrumbList>
+            <BreadcrumbItem>
+              <BreadcrumbLink href="#">首页</BreadcrumbLink>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem>
+              <BreadcrumbLink href="#">实例列表</BreadcrumbLink>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+            <BreadcrumbItem>
+              <BreadcrumbPage>实例详情</BreadcrumbPage>
+            </BreadcrumbItem>
+          </BreadcrumbList>
+        </Breadcrumb>
+        <div className="flex items-center gap-4">
+          <a
+            href="#"
+            className="inline-flex items-center gap-1 text-muted-foreground hover:text-foreground"
+          >
+            <BookOpen className="size-3.5" aria-hidden="true" />
+            帮助文档
+          </a>
+          <a href="#" className="text-muted-foreground hover:text-foreground">
+            切换实例
+          </a>
+        </div>
+      </PageHeaderNav>
+      <PageHeaderContent>
+        <div className="flex flex-col">
+          <PageHeaderHeading goBack onBack={() => alert('返回')}>
+            <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 tooltip="该实例为生产环境，建议谨慎操作。">
+              页面标题
+            </PageHeaderTitle>
+            <Tag variant="solid" color="success" size="lg">
+              标签一
+            </Tag>
+            <Tag variant="solid" color="primary" size="lg">
+              标签二
+            </Tag>
+            <Tag variant="solid" color="destructive" size="lg">
+              标签三
+            </Tag>
+          </PageHeaderHeading>
+          <PageHeaderDescription>
+            页面描述页面描述页面描述页面描述页面描述页面描述页面描述
+          </PageHeaderDescription>
+        </div>
+        <PageHeaderActions>
+          <Button variant="outline">普通按钮</Button>
+          <Button>主要按钮</Button>
+        </PageHeaderActions>
+      </PageHeaderContent>
+    </PageHeader>
+  ),
+};
+
+/** 带数据概览：右侧使用 Statistic 组件展示 KPI 指标。 */
+export const WithStatistic: Story = {
+  render: () => (
+    <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>
+  ),
+};
+
+/** 带描述列表：底部使用 Descriptions 组件展示项目详细信息。 */
+export const WithDescriptions: Story = {
+  render: () => (
+    <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>
+  ),
+};
+
+/** 带视图切换：标题旁使用 ToggleGroup 切换视图模式。 */
+export const WithViewToggle: Story = {
+  render: () => (
+    <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>
+  ),
+};
+
+/** 右侧装饰图版本：无操作按钮，右侧用 lucide icon（Cloud）放大 + 半透明作背景插画。 */
+export const WithBackgroundIllustration: Story = {
+  render: () => (
+    <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>
+  ),
+};
+
+/** 带返回按钮的详情页头。 */
+export const WithGoBack: Story = {
+  render: () => (
+    <PageHeader>
+      <PageHeaderContent>
+        <PageHeaderHeading goBack onBack={() => alert('返回')}>
+          <PageHeaderTitle>详情页标题</PageHeaderTitle>
+        </PageHeaderHeading>
+        <PageHeaderActions>
+          <Button>操作</Button>
+        </PageHeaderActions>
+      </PageHeaderContent>
+      <PageHeaderDescription>补充描述信息。</PageHeaderDescription>
+    </PageHeader>
+  ),
+};

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

@@ -0,0 +1,119 @@
+/**
+ * 页面骨架 PageShell
+ *
+ * 页面级布局壳，组合 header + sidebar + 主区三个 slot，
+ * 覆盖全屏、仅顶部、仅左导、顶部+左导四种页面形态。
+ *
+ * @when
+ * - 搭建应用级页面布局（管理后台、控制台）
+ * - 需要 header + sidebar + content 三栏组合
+ * - 需要可切换的页面背景色
+ *
+ * 组合结构：PageShell > header(slot) + sidebar(slot) + children
+ */
+'use client';
+
+import * as React from 'react';
+
+import { cn } from '@/lib/utils';
+import { SidebarInset, SidebarProvider } from '@/components/sidebar';
+
+export type PageShellBackground =
+  | 'background'
+  | 'muted'
+  | 'card'
+  | 'sidebar'
+  | 'accent';
+
+const BG_CLASS: Record<PageShellBackground, string> = {
+  background: 'bg-background',
+  muted: 'bg-muted',
+  card: 'bg-card',
+  sidebar: 'bg-sidebar',
+  accent: 'bg-accent',
+};
+
+export interface PageShellProps extends React.ComponentProps<'div'> {
+  /** 顶部条 slot — 通常是 Navbar / TopBar，不传则不渲染顶部 */
+  header?: React.ReactNode;
+  /** 左侧 slot — 通常是 Sidebar 组件，不传则不渲染侧边栏 */
+  sidebar?: React.ReactNode;
+  /** 主区内容 */
+  children: React.ReactNode;
+  /**
+   * 主区背景，走 shadcn 语义槽枚举
+   * @default "background"
+   */
+  background?: PageShellBackground;
+  /**
+   * sidebar 宽度，透传 SidebarProvider 的 --sidebar-width
+   * @default "14rem"
+   */
+  sidebarWidth?: string;
+}
+
+function PageShell({
+  header,
+  sidebar,
+  children,
+  background = 'background',
+  sidebarWidth = '14rem',
+  className,
+  style,
+  ...props
+}: PageShellProps) {
+  const bgClass = BG_CLASS[background];
+
+  if (!sidebar) {
+    return (
+      <div
+        data-slot="page-shell"
+        className={cn('flex min-h-svh w-full flex-col', className)}
+        style={style}
+        {...props}
+      >
+        {header}
+        <main
+          data-slot="page-shell-content"
+          className={cn('flex-1 overflow-y-auto', bgClass)}
+        >
+          {children}
+        </main>
+      </div>
+    );
+  }
+
+  return (
+    <SidebarProvider
+      data-slot="page-shell"
+      // SidebarProvider 默认 wrapper 是 `flex min-h-svh`（row）；
+      // PageShell 需要 column 排列（header 在上，sidebar+主区在下），故 `!flex-col` 覆盖。
+      // 高度策略：保留 SidebarProvider 默认 `min-h-svh` 让 wrapper 真实页面下撑满 viewport，
+      // 这样 OpPageContainer 等内嵌容器的 `flex-1` 链路能拿到稳定高度全高渲染。
+      // 受限容器（如 storybook `LayoutSandbox`）通过外级注入 `min-height: 0; height: 100%` 重置。
+      // 说明：传入的 sidebar 如果是默认 collapsible="offcanvas"，其内部使用 `position: fixed`、
+      // 高度 100svh，适用于全屏页面；在受限容器中需使用 `collapsible="none"` 退出 fixed 布局。
+      className={cn('!flex-col', className)}
+      style={
+        {
+          '--sidebar-width': sidebarWidth,
+          ...style,
+        } as React.CSSProperties
+      }
+      {...props}
+    >
+      {header}
+      <div className="flex w-full flex-1 min-h-0">
+        {sidebar}
+        <SidebarInset
+          data-slot="page-shell-content"
+          className={cn('!min-h-0 overflow-y-auto', bgClass)}
+        >
+          {children}
+        </SidebarInset>
+      </div>
+    </SidebarProvider>
+  );
+}
+
+export { PageShell };

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

@@ -0,0 +1,115 @@
+# PageShell
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+页面骨架 PageShell
+页面级布局壳，组合 header + sidebar + 主区三个 slot，
+覆盖全屏、仅顶部、仅左导、顶部+左导四种页面形态。
+
+## 使用场景
+
+- 搭建应用级页面布局（管理后台、控制台）
+- 需要 header + sidebar + content 三栏组合
+- 需要可切换的页面背景色
+- 组合结构：PageShell > header(slot) + sidebar(slot) + children
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `header` | `React.ReactNode` | – | – | 顶部条 slot — 通常是 Navbar / TopBar，不传则不渲染顶部 |
+| `sidebar` | `React.ReactNode` | – | – | 左侧 slot — 通常是 Sidebar 组件，不传则不渲染侧边栏 |
+| `children` | `React.ReactNode` | – | ✓ | 主区内容 |
+| `background` | `PageShellBackground` | `"background"` | – | 主区背景，走 shadcn 语义槽枚举 |
+| `sidebarWidth` | `string` | `"14rem"` | – | sidebar 宽度，透传 SidebarProvider 的 --sidebar-width |
+
+## 示例
+
+### HeaderOnly
+
+仅顶部条 + 主区。
+
+```tsx
+<PageShell
+  header={
+    <div className="flex h-12 items-center border-b border-border px-4">
+      <span className="text-xs text-muted-foreground">Header</span>
+    </div>
+  }
+  className="h-64 rounded-md border border-border"
+>
+  <div className="p-4">
+    <span className="text-xs text-muted-foreground">主区内容</span>
+  </div>
+</PageShell>
+```
+
+### Fullscreen
+
+全屏模式（无 header 无 sidebar）。
+
+```tsx
+<PageShell className="h-64 rounded-md border border-border">
+  <div className="flex h-full items-center justify-center">
+    <span className="text-xs text-muted-foreground">全屏内容</span>
+  </div>
+</PageShell>
+```
+
+### MutedBackground
+
+使用 muted 背景色。
+
+```tsx
+<PageShell
+  background="muted"
+  header={
+    <div className="flex h-12 items-center border-b border-border bg-background px-4">
+      <span className="text-xs text-muted-foreground">Header</span>
+    </div>
+  }
+  className="h-64 rounded-md border border-border"
+>
+  <div className="p-4">
+    <span className="text-xs text-muted-foreground">muted 背景主区</span>
+  </div>
+</PageShell>
+```
+
+### WithSidebar
+
+带左侧 Sidebar 的页面骨架。 Storybook 受限容器内使用 `collapsible="none"` 的内联 Sidebar； 真实业务页面建议用全屏布局 + 默认 offcanvas 折叠形态。
+
+```tsx
+<PageShell
+  sidebar={<SidebarNav />}
+  className="h-96 rounded-md border border-border overflow-hidden"
+>
+  <div className="p-4">
+    <span className="text-xs text-muted-foreground">主区内容</span>
+  </div>
+</PageShell>
+```
+
+### HeaderWithSidebar
+
+顶部 Header + 左侧 Sidebar 的组合形态。
+
+```tsx
+<PageShell
+  header={
+    <div className="flex h-12 shrink-0 items-center border-b border-border bg-background px-4">
+      <span className="text-xs text-muted-foreground">Header</span>
+    </div>
+  }
+  sidebar={<SidebarNav />}
+  background="muted"
+  className="h-96 rounded-md border border-border overflow-hidden"
+>
+  <div className="p-4">
+    <span className="text-xs text-muted-foreground">主区内容</span>
+  </div>
+</PageShell>
+```

package/src/components/page-shell/stories.tsx

@@ -0,0 +1,154 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  HomeIcon,
+  InboxIcon,
+  CalendarIcon,
+  SearchIcon,
+  SettingsIcon,
+} from 'lucide-react';
+import {
+  Sidebar,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+} from '@/components/sidebar';
+import { PageShell } from './index';
+
+const meta: Meta<typeof PageShell> = {
+  title: '布局 · Layout/PageShell 页面骨架',
+  component: PageShell,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 仅顶部条 + 主区。 */
+export const HeaderOnly: Story = {
+  render: () => (
+    <PageShell
+      header={
+        <div className="flex h-12 items-center border-b border-border px-4">
+          <span className="text-xs text-muted-foreground">Header</span>
+        </div>
+      }
+      className="h-64 rounded-md border border-border"
+    >
+      <div className="p-4">
+        <span className="text-xs text-muted-foreground">主区内容</span>
+      </div>
+    </PageShell>
+  ),
+};
+
+/** 全屏模式（无 header 无 sidebar）。 */
+export const Fullscreen: Story = {
+  render: () => (
+    <PageShell className="h-64 rounded-md border border-border">
+      <div className="flex h-full items-center justify-center">
+        <span className="text-xs text-muted-foreground">全屏内容</span>
+      </div>
+    </PageShell>
+  ),
+};
+
+/** 使用 muted 背景色。 */
+export const MutedBackground: Story = {
+  render: () => (
+    <PageShell
+      background="muted"
+      header={
+        <div className="flex h-12 items-center border-b border-border bg-background px-4">
+          <span className="text-xs text-muted-foreground">Header</span>
+        </div>
+      }
+      className="h-64 rounded-md border border-border"
+    >
+      <div className="p-4">
+        <span className="text-xs text-muted-foreground">muted 背景主区</span>
+      </div>
+    </PageShell>
+  ),
+};
+
+const navItems = [
+  { title: '首页', icon: HomeIcon },
+  { title: '收件箱', icon: InboxIcon },
+  { title: '日历', icon: CalendarIcon },
+  { title: '搜索', icon: SearchIcon },
+  { title: '设置', icon: SettingsIcon },
+];
+
+function SidebarNav() {
+  return (
+    <Sidebar
+      collapsible="none"
+      className="h-full border-r border-sidebar-border"
+    >
+      <SidebarHeader>
+        <span className="px-2 text-sm font-medium">应用名称</span>
+      </SidebarHeader>
+      <SidebarContent>
+        <SidebarGroup>
+          <SidebarGroupLabel>导航</SidebarGroupLabel>
+          <SidebarGroupContent>
+            <SidebarMenu>
+              {navItems.map((item) => (
+                <SidebarMenuItem key={item.title}>
+                  <SidebarMenuButton>
+                    <item.icon />
+                    <span>{item.title}</span>
+                  </SidebarMenuButton>
+                </SidebarMenuItem>
+              ))}
+            </SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
+      </SidebarContent>
+    </Sidebar>
+  );
+}
+
+/**
+ * 带左侧 Sidebar 的页面骨架。
+ *
+ * Storybook 受限容器内使用 `collapsible="none"` 的内联 Sidebar；
+ * 真实业务页面建议用全屏布局 + 默认 offcanvas 折叠形态。
+ */
+export const WithSidebar: Story = {
+  render: () => (
+    <PageShell
+      sidebar={<SidebarNav />}
+      className="h-96 rounded-md border border-border overflow-hidden"
+    >
+      <div className="p-4">
+        <span className="text-xs text-muted-foreground">主区内容</span>
+      </div>
+    </PageShell>
+  ),
+};
+
+/** 顶部 Header + 左侧 Sidebar 的组合形态。 */
+export const HeaderWithSidebar: Story = {
+  render: () => (
+    <PageShell
+      header={
+        <div className="flex h-12 shrink-0 items-center border-b border-border bg-background px-4">
+          <span className="text-xs text-muted-foreground">Header</span>
+        </div>
+      }
+      sidebar={<SidebarNav />}
+      background="muted"
+      className="h-96 rounded-md border border-border overflow-hidden"
+    >
+      <div className="p-4">
+        <span className="text-xs text-muted-foreground">主区内容</span>
+      </div>
+    </PageShell>
+  ),
+};