@teamix-evo/ui 0.1.1

package/src/components/sidebar/sidebar.tsx

@@ -0,0 +1,351 @@
+import * as React from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { PanelLeft } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+import { Button } from '@/components/button/button';
+import { Separator } from '@/components/separator/separator';
+
+// ─── Context + Provider ──────────────────────────────────────────────────────
+
+interface SidebarContextValue {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  toggle: () => void;
+}
+
+const SidebarContext = React.createContext<SidebarContextValue | null>(null);
+
+export function useSidebar() {
+  const ctx = React.useContext(SidebarContext);
+  if (!ctx) {
+    throw new Error('useSidebar must be used within <SidebarProvider>');
+  }
+  return ctx;
+}
+
+export interface SidebarProviderProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** 受控 open 状态。 */
+  open?: boolean;
+  /** uncontrolled 初始状态。 @default true */
+  defaultOpen?: boolean;
+  /** open 状态变化回调。 */
+  onOpenChange?: (open: boolean) => void;
+}
+
+const SidebarProvider = React.forwardRef<HTMLDivElement, SidebarProviderProps>(
+  (
+    {
+      defaultOpen = true,
+      open: openProp,
+      onOpenChange,
+      className,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const [internal, setInternal] = React.useState(defaultOpen);
+    const isControlled = openProp !== undefined;
+    const open = isControlled ? (openProp as boolean) : internal;
+
+    const setOpen = React.useCallback(
+      (next: boolean) => {
+        if (!isControlled) setInternal(next);
+        onOpenChange?.(next);
+      },
+      [isControlled, onOpenChange],
+    );
+    const toggle = React.useCallback(() => setOpen(!open), [open, setOpen]);
+
+    const value = React.useMemo<SidebarContextValue>(
+      () => ({ open, setOpen, toggle }),
+      [open, setOpen, toggle],
+    );
+
+    return (
+      <SidebarContext.Provider value={value}>
+        <div
+          ref={ref}
+          data-state={open ? 'expanded' : 'collapsed'}
+          className={cn(
+            'group/sidebar-wrapper flex min-h-svh w-full',
+            className,
+          )}
+          {...props}
+        >
+          {children}
+        </div>
+      </SidebarContext.Provider>
+    );
+  },
+);
+SidebarProvider.displayName = 'SidebarProvider';
+
+// ─── Main Sidebar container ───────────────────────────────────────────────────
+
+const sidebarVariants = cva(
+  'flex h-svh shrink-0 flex-col border-r bg-background transition-[width] duration-200 ease-linear',
+  {
+    variants: {
+      side: {
+        left: 'border-r',
+        right: 'border-l border-r-0 order-last',
+      },
+    },
+    defaultVariants: { side: 'left' },
+  },
+);
+
+export interface SidebarProps
+  extends React.HTMLAttributes<HTMLElement>,
+    VariantProps<typeof sidebarVariants> {
+  /**
+   * 侧边方向。
+   * @default "left"
+   */
+  side?: 'left' | 'right';
+  /**
+   * 折叠模式 — `icon` 折叠后只剩图标列(64px);`offcanvas` 完全收起(0px)。
+   * @default "icon"
+   */
+  collapsible?: 'icon' | 'offcanvas' | 'none';
+  /** 展开宽度。 @default "16rem" */
+  width?: string;
+  /** 折叠后宽度(`collapsible="icon"` 时生效)。 @default "3rem" */
+  collapsedWidth?: string;
+}
+
+const Sidebar = React.forwardRef<HTMLElement, SidebarProps>(
+  (
+    {
+      side = 'left',
+      collapsible = 'icon',
+      width = '16rem',
+      collapsedWidth = '3rem',
+      className,
+      style,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const { open } = useSidebar();
+    const w =
+      collapsible === 'none'
+        ? width
+        : open
+          ? width
+          : collapsible === 'icon'
+            ? collapsedWidth
+            : '0px';
+    return (
+      <aside
+        ref={ref}
+        data-state={open ? 'expanded' : 'collapsed'}
+        data-collapsible={collapsible}
+        data-side={side}
+        style={{ width: w, ...style }}
+        className={cn(
+          sidebarVariants({ side }),
+          collapsible === 'offcanvas' && !open && 'overflow-hidden',
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </aside>
+    );
+  },
+);
+Sidebar.displayName = 'Sidebar';
+
+// ─── Sub-components ──────────────────────────────────────────────────────────
+
+const SidebarHeader = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex flex-col gap-2 p-2', className)}
+    {...props}
+  />
+));
+SidebarHeader.displayName = 'SidebarHeader';
+
+const SidebarFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('mt-auto flex flex-col gap-2 p-2', className)}
+    {...props}
+  />
+));
+SidebarFooter.displayName = 'SidebarFooter';
+
+const SidebarSeparator = React.forwardRef<
+  React.ElementRef<typeof Separator>,
+  React.ComponentPropsWithoutRef<typeof Separator>
+>(({ className, ...props }, ref) => (
+  <Separator
+    ref={ref}
+    className={cn('mx-2 w-auto bg-border', className)}
+    {...props}
+  />
+));
+SidebarSeparator.displayName = 'SidebarSeparator';
+
+const SidebarContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      'flex min-h-0 flex-1 flex-col gap-2 overflow-auto p-2',
+      className,
+    )}
+    {...props}
+  />
+));
+SidebarContent.displayName = 'SidebarContent';
+
+const SidebarGroup = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex w-full min-w-0 flex-col gap-1', className)}
+    {...props}
+  />
+));
+SidebarGroup.displayName = 'SidebarGroup';
+
+const SidebarGroupLabel = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => {
+  const { open } = useSidebar();
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        'flex h-8 shrink-0 items-center px-2 text-xs font-medium text-muted-foreground',
+        !open && 'opacity-0',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+SidebarGroupLabel.displayName = 'SidebarGroupLabel';
+
+const SidebarMenu = React.forwardRef<
+  HTMLUListElement,
+  React.HTMLAttributes<HTMLUListElement>
+>(({ className, ...props }, ref) => (
+  <ul
+    ref={ref}
+    className={cn('flex w-full min-w-0 flex-col gap-1', className)}
+    {...props}
+  />
+));
+SidebarMenu.displayName = 'SidebarMenu';
+
+const SidebarMenuItem = React.forwardRef<
+  HTMLLIElement,
+  React.HTMLAttributes<HTMLLIElement>
+>(({ className, ...props }, ref) => (
+  <li ref={ref} className={cn('group/menu-item', className)} {...props} />
+));
+SidebarMenuItem.displayName = 'SidebarMenuItem';
+
+export interface SidebarMenuButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /** 当前激活态(高亮显示)。 */
+  isActive?: boolean;
+  /** 用 Slot 渲染为子元素(配合 router Link)。 */
+  asChild?: boolean;
+}
+
+const SidebarMenuButton = React.forwardRef<
+  HTMLButtonElement,
+  SidebarMenuButtonProps
+>(({ className, isActive, asChild, ...props }, ref) => {
+  const Comp = asChild ? Slot : 'button';
+  return (
+    <Comp
+      ref={ref}
+      data-active={isActive ? 'true' : undefined}
+      className={cn(
+        'flex h-8 w-full items-center gap-2 overflow-hidden rounded-md px-2 text-left text-sm outline-none ring-ring transition hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50 data-[active=true]:bg-accent data-[active=true]:font-medium data-[active=true]:text-accent-foreground [&_svg]:size-4 [&_svg]:shrink-0',
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+SidebarMenuButton.displayName = 'SidebarMenuButton';
+
+// ─── Trigger ─────────────────────────────────────────────────────────────────
+
+const SidebarTrigger = React.forwardRef<
+  HTMLButtonElement,
+  React.ComponentPropsWithoutRef<typeof Button>
+>(({ className, onClick, ...props }, ref) => {
+  const { toggle } = useSidebar();
+  return (
+    <Button
+      ref={ref}
+      variant="ghost"
+      size="icon"
+      className={cn('size-7', className)}
+      onClick={(e) => {
+        onClick?.(e);
+        toggle();
+      }}
+      aria-label="Toggle Sidebar"
+      {...props}
+    >
+      <PanelLeft />
+      <span className="sr-only">Toggle Sidebar</span>
+    </Button>
+  );
+});
+SidebarTrigger.displayName = 'SidebarTrigger';
+
+// ─── Inset(主内容区,与 Sidebar 配合)─────────────────────────────────────
+
+const SidebarInset = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <main
+    ref={ref}
+    className={cn('relative flex min-h-svh flex-1 flex-col bg-background', className)}
+    {...(props as React.HTMLAttributes<HTMLElement>)}
+  />
+));
+SidebarInset.displayName = 'SidebarInset';
+
+export {
+  SidebarProvider,
+  Sidebar,
+  SidebarHeader,
+  SidebarFooter,
+  SidebarSeparator,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupLabel,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarTrigger,
+  SidebarInset,
+};

package/src/components/skeleton/skeleton.meta.md

@@ -0,0 +1,95 @@
+---
+id: skeleton
+name: Skeleton
+type: component
+category: foundation
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Skeleton
+
+骨架屏占位 — shadcn 单元素 pulse + antd 子组件家族(`SkeletonAvatar / SkeletonImage / SkeletonButton / SkeletonInput / SkeletonParagraph`)。
+
+`motion-reduce:animate-none` 自动尊重用户的"减少动画"系统设置。
+
+## When to use
+
+- 首屏 / 路由切换数据加载中
+- 列表 / 卡片网格的预占位(避免布局抖动)
+- 替代 Spinner 用于"内容形状已知"的等待场景
+
+## When NOT to use
+
+- 加载时间已知 < 300ms → 直接渲染最终态
+- 真正失败 / 空数据 → 用 `Empty` 或 `Alert`(v0.x)
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `shape` | `'rect' \| 'circle' \| 'line'` | `"rect"` | – | 形状变体。`rect` 默认矩形;`circle` 圆形(用于 Avatar 占位);`line` 单行文本占位。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add skeleton` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add class-variance-authority@^0.7.0
+```
+<!-- auto:deps:end -->
+
+> 子组件 `SkeletonAvatar / SkeletonImage / SkeletonButton / SkeletonInput / SkeletonParagraph` 各自的 Props 可在 [`skeleton.tsx`](./skeleton.tsx) 查看。
+
+## AI 生成纪律
+
+- **形状要与最终内容匹配**:文本用 `shape="line"`,头像用 `<SkeletonAvatar />`,图片用 `<SkeletonImage />`,**不要**全用矩形糊弄
+- **段落用 SkeletonParagraph**:不要手写多个 `<Skeleton shape="line" />`,失去尾行收窄的自然观感
+- **不要嵌套到 disabled state**:loading 状态优先用 Skeleton 替代整块,而非 Skeleton 叠加在 disabled 内容上
+- **`aria-hidden` 已自动**:不要给 Skeleton 加文字 children 或 aria-label,屏幕阅读器应跳过
+
+## Examples
+
+```tsx
+import {
+  Skeleton,
+  SkeletonAvatar,
+  SkeletonImage,
+  SkeletonParagraph,
+} from '@/components/ui/skeleton';
+
+// 基础
+<Skeleton className="h-8 w-32" />
+
+// 头像 + 双行
+<div className="flex items-center gap-3">
+  <SkeletonAvatar />
+  <div className="flex flex-col gap-2">
+    <Skeleton shape="line" className="w-32" />
+    <Skeleton shape="line" className="w-24" />
+  </div>
+</div>
+
+// 卡片占位
+<div className="rounded-lg border p-4">
+  <SkeletonImage />
+  <SkeletonParagraph rows={3} className="mt-3" />
+</div>
+```

package/src/components/skeleton/skeleton.stories.tsx

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Skeleton,
+  SkeletonAvatar,
+  SkeletonImage,
+  SkeletonButton,
+  SkeletonInput,
+  SkeletonParagraph,
+} from './skeleton';
+
+const meta: Meta<typeof Skeleton> = {
+  title: '基础原语 · Foundation/Skeleton',
+  component: Skeleton,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '骨架屏 — 在内容加载过程中呈现占位图形，减少加载期间的视觉跳动。shadcn `Skeleton` 原子 + antd `Skeleton` 的能力并集：除原子 `Skeleton`（支持 `shape: rect | circle | line`）外，同时提供预设组合 `SkeletonAvatar` / `SkeletonImage` / `SkeletonButton` / `SkeletonInput` / `SkeletonParagraph`。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    shape: { control: 'inline-radio', options: ['rect', 'circle', 'line'] },
+  },
+  args: { shape: 'rect', className: 'h-8 w-32' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Skeleton>;
+
+export const Playground: Story = {};
+
+export const Family: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex items-center gap-3">
+        <SkeletonAvatar size="sm" />
+        <SkeletonAvatar />
+        <SkeletonAvatar size="lg" />
+      </div>
+      <div className="flex items-center gap-3">
+        <SkeletonButton size="sm" />
+        <SkeletonButton />
+        <SkeletonButton size="lg" />
+      </div>
+      <div className="w-72">
+        <SkeletonInput />
+      </div>
+      <div className="w-72">
+        <SkeletonImage />
+      </div>
+    </div>
+  ),
+};
+
+export const Card: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-80 rounded-lg border p-4">
+      <SkeletonImage />
+      <SkeletonParagraph rows={3} className="mt-3" />
+    </div>
+  ),
+};
+
+export const ListItem: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-72 items-center gap-3">
+      <SkeletonAvatar />
+      <div className="flex flex-1 flex-col gap-2">
+        <Skeleton shape="line" className="w-32" />
+        <Skeleton shape="line" className="w-24" />
+      </div>
+    </div>
+  ),
+};

package/src/components/skeleton/skeleton.tsx

@@ -0,0 +1,144 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/utils/cn';
+
+const skeletonVariants = cva(
+  'animate-pulse rounded-md bg-muted motion-reduce:animate-none',
+  {
+    variants: {
+      shape: {
+        rect: '',
+        circle: 'rounded-full',
+        line: 'h-3',
+      },
+    },
+    defaultVariants: { shape: 'rect' },
+  },
+);
+
+export interface SkeletonProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>,
+    VariantProps<typeof skeletonVariants> {
+  /**
+   * 形状变体。`rect` 默认矩形;`circle` 圆形(用于 Avatar 占位);`line` 单行文本占位。
+   * @default "rect"
+   */
+  shape?: 'rect' | 'circle' | 'line';
+}
+
+const Skeleton = React.forwardRef<HTMLDivElement, SkeletonProps>(
+  ({ className, shape, ...props }, ref) => (
+    <div
+      ref={ref}
+      aria-hidden="true"
+      className={cn(skeletonVariants({ shape }), className)}
+      {...props}
+    />
+  ),
+);
+Skeleton.displayName = 'Skeleton';
+
+// ─── antd-style sub-components(Avatar / Image / Button / Input / Paragraph)─
+
+export interface SkeletonAvatarProps extends Omit<SkeletonProps, 'shape'> {
+  /** 尺寸:小 32 / 默认 40 / 大 64。 @default "default" */
+  size?: 'sm' | 'default' | 'lg';
+}
+const SkeletonAvatar = React.forwardRef<HTMLDivElement, SkeletonAvatarProps>(
+  ({ size = 'default', className, ...props }, ref) => {
+    const dim = size === 'sm' ? 'size-8' : size === 'lg' ? 'size-16' : 'size-10';
+    return (
+      <Skeleton
+        ref={ref}
+        shape="circle"
+        className={cn(dim, className)}
+        {...props}
+      />
+    );
+  },
+);
+SkeletonAvatar.displayName = 'SkeletonAvatar';
+
+export interface SkeletonImageProps extends Omit<SkeletonProps, 'shape'> {}
+const SkeletonImage = React.forwardRef<HTMLDivElement, SkeletonImageProps>(
+  ({ className, ...props }, ref) => (
+    <Skeleton
+      ref={ref}
+      shape="rect"
+      className={cn('aspect-video w-full', className)}
+      {...props}
+    />
+  ),
+);
+SkeletonImage.displayName = 'SkeletonImage';
+
+export interface SkeletonButtonProps extends Omit<SkeletonProps, 'shape'> {
+  size?: 'sm' | 'default' | 'lg';
+}
+const SkeletonButton = React.forwardRef<HTMLDivElement, SkeletonButtonProps>(
+  ({ size = 'default', className, ...props }, ref) => {
+    const h = size === 'sm' ? 'h-8' : size === 'lg' ? 'h-10' : 'h-9';
+    return (
+      <Skeleton
+        ref={ref}
+        shape="rect"
+        className={cn(h, 'w-24', className)}
+        {...props}
+      />
+    );
+  },
+);
+SkeletonButton.displayName = 'SkeletonButton';
+
+export interface SkeletonInputProps extends Omit<SkeletonProps, 'shape'> {}
+const SkeletonInput = React.forwardRef<HTMLDivElement, SkeletonInputProps>(
+  ({ className, ...props }, ref) => (
+    <Skeleton
+      ref={ref}
+      shape="rect"
+      className={cn('h-9 w-full', className)}
+      {...props}
+    />
+  ),
+);
+SkeletonInput.displayName = 'SkeletonInput';
+
+export interface SkeletonParagraphProps
+  extends Omit<SkeletonProps, 'shape'> {
+  /**
+   * 段落行数。最后一行宽度自动收窄至 60%,模拟自然段尾。
+   * @default 3
+   */
+  rows?: number;
+}
+const SkeletonParagraph = React.forwardRef<
+  HTMLDivElement,
+  SkeletonParagraphProps
+>(({ rows = 3, className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex flex-col gap-2', className)}
+    aria-hidden="true"
+    {...props}
+  >
+    {Array.from({ length: rows }).map((_, i) => (
+      <Skeleton
+        key={i}
+        shape="line"
+        className={i === rows - 1 ? 'w-3/5' : 'w-full'}
+      />
+    ))}
+  </div>
+));
+SkeletonParagraph.displayName = 'SkeletonParagraph';
+
+export {
+  Skeleton,
+  SkeletonAvatar,
+  SkeletonImage,
+  SkeletonButton,
+  SkeletonInput,
+  SkeletonParagraph,
+  skeletonVariants,
+};