@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/skeleton/index.tsx

@@ -0,0 +1,415 @@
+/**
+ * 骨架屏 Skeleton
+ *
+ * 内容加载时的占位动画，提升感知加载速度。提供 base Skeleton 与 6 个子家族
+ * (Avatar / Image / Button / Input / Title / Paragraph) 用于一行替换占位。
+ *
+ * 组合结构：Skeleton（base） · SkeletonAvatar / SkeletonImage / SkeletonButton /
+ * SkeletonInput / SkeletonTitle / SkeletonParagraph（独立子家族，可单独或组合使用）
+ *
+ * @when
+ * - 页面或区块初次加载时展示内容占位
+ * - 列表 / 卡片 / 详情数据加载中
+ * - 头像、图片、按钮、输入框等具体形态的加载占位
+ */
+
+import * as React from 'react';
+import { Slot } from 'radix-ui';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { ImageIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+
+// ─── base Skeleton ──────────────────────────────────────────────────────────
+
+const skeletonVariants = cva('shrink-0 bg-muted', {
+  variants: {
+    variant: {
+      text: 'h-4 w-full rounded-sm',
+      rectangular: '',
+      rounded: 'rounded-md',
+      circular: 'aspect-square rounded-full',
+    },
+    animation: {
+      pulse: 'animate-pulse motion-reduce:animate-none',
+      none: '',
+    },
+  },
+  defaultVariants: {
+    variant: 'rounded',
+    animation: 'pulse',
+  },
+});
+
+export type SkeletonVariant = 'text' | 'rectangular' | 'rounded' | 'circular';
+export type SkeletonAnimation = 'pulse' | 'none';
+
+export interface SkeletonProps
+  extends Omit<React.ComponentProps<'div'>, 'children'>,
+    VariantProps<typeof skeletonVariants> {
+  /** 形状变体：text 行高占位 / rectangular 矩形 / rounded 圆角矩形 / circular 圆形。 @default rounded */
+  variant?: SkeletonVariant;
+  /** 动画类型：pulse 呼吸 / none 静默；用户开启 reduced motion 时自动降级。 @default pulse */
+  animation?: SkeletonAnimation;
+  /** 宽度，数字按 px 解析；与 className 同存时 inline style 优先 */
+  width?: number | string;
+  /** 高度，数字按 px 解析 */
+  height?: number | string;
+  /** 加载条件渲染：true 显示骨架；false 直接渲染 children（antd 风格）。@default true */
+  loading?: boolean;
+  /** Slot 模式，将骨架样式应用到子元素上。@default false */
+  asChild?: boolean;
+  /** 子内容；loading=false 时直接显示 children */
+  children?: React.ReactNode;
+}
+
+function toLength(v: number | string | undefined): string | undefined {
+  if (v === undefined) return undefined;
+  return typeof v === 'number' ? `${v}px` : v;
+}
+
+function Skeleton({
+  className,
+  variant,
+  animation,
+  width,
+  height,
+  loading,
+  asChild = false,
+  style,
+  children,
+  ...rest
+}: SkeletonProps) {
+  if (loading === false) return <>{children}</>;
+
+  const Comp = asChild ? Slot.Root : 'div';
+
+  const sizeStyle: React.CSSProperties = {};
+  const w = toLength(width);
+  const h = toLength(height);
+  if (w !== undefined) sizeStyle.width = w;
+  if (h !== undefined) sizeStyle.height = h;
+
+  return (
+    <Comp
+      data-slot="skeleton"
+      data-variant={variant}
+      data-animation={animation}
+      className={cn(skeletonVariants({ variant, animation }), className)}
+      style={{ ...sizeStyle, ...style }}
+      {...rest}
+    >
+      {children}
+    </Comp>
+  );
+}
+
+// ─── SkeletonAvatar ─────────────────────────────────────────────────────────
+
+const skeletonAvatarVariants = cva('', {
+  variants: {
+    size: {
+      sm: 'size-6',
+      default: 'size-8',
+      lg: 'size-10',
+    },
+  },
+  defaultVariants: {
+    size: 'default',
+  },
+});
+
+export type SkeletonAvatarSize = 'sm' | 'default' | 'lg';
+
+export interface SkeletonAvatarProps
+  extends Omit<SkeletonProps, 'variant' | 'width' | 'height'> {
+  /** 头像尺寸；可传枚举或数字（数字按 px 当作宽高）。@default default */
+  size?: SkeletonAvatarSize | number;
+  /** 头像形状。@default circle */
+  shape?: 'circle' | 'square';
+}
+
+function SkeletonAvatar({
+  className,
+  size = 'default',
+  shape = 'circle',
+  ...props
+}: SkeletonAvatarProps) {
+  const variant = shape === 'square' ? 'rounded' : 'circular';
+  const isCustomSize = typeof size === 'number';
+  const sizeClass = isCustomSize
+    ? ''
+    : skeletonAvatarVariants({ size: size as SkeletonAvatarSize });
+
+  return (
+    <Skeleton
+      data-slot="skeleton-avatar"
+      data-shape={shape}
+      variant={variant}
+      width={isCustomSize ? size : undefined}
+      height={isCustomSize ? size : undefined}
+      className={cn(sizeClass, className)}
+      {...props}
+    />
+  );
+}
+
+// ─── SkeletonImage ──────────────────────────────────────────────────────────
+
+const skeletonImageVariants = cva(
+  'flex items-center justify-center rounded-md text-muted-foreground/60 [&>svg]:size-1/3',
+  {
+    variants: {
+      size: {
+        sm: 'size-16',
+        default: 'size-24',
+        lg: 'size-32',
+      },
+      block: {
+        true: 'aspect-video size-auto w-full',
+        false: '',
+      },
+    },
+    defaultVariants: {
+      size: 'default',
+      block: false,
+    },
+  },
+);
+
+export type SkeletonImageSize = 'sm' | 'default' | 'lg';
+
+export interface SkeletonImageProps
+  extends Omit<SkeletonProps, 'variant' | 'children'> {
+  /** 图片骨架尺寸。@default default */
+  size?: SkeletonImageSize;
+  /** true 时撑满父容器宽度并按 16:9 比例显示。@default false */
+  block?: boolean;
+  /** 自定义占位图标节点；不传则使用 lucide ImageIcon */
+  icon?: React.ReactNode;
+}
+
+function SkeletonImage({
+  className,
+  size = 'default',
+  block = false,
+  icon,
+  ...props
+}: SkeletonImageProps) {
+  return (
+    <Skeleton
+      data-slot="skeleton-image"
+      data-size={size}
+      variant="rectangular"
+      className={cn(skeletonImageVariants({ size, block }), className)}
+      {...props}
+    >
+      {icon ?? <ImageIcon aria-hidden="true" />}
+    </Skeleton>
+  );
+}
+
+// ─── SkeletonButton ─────────────────────────────────────────────────────────
+
+const skeletonButtonVariants = cva('rounded-md', {
+  variants: {
+    size: {
+      sm: 'h-6 w-16',
+      default: 'h-8 w-20',
+      lg: 'h-9 w-24',
+      icon: 'size-8',
+    },
+    block: {
+      true: 'w-full',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    size: 'default',
+    block: false,
+  },
+});
+
+export type SkeletonButtonSize = 'sm' | 'default' | 'lg' | 'icon';
+
+export interface SkeletonButtonProps
+  extends Omit<SkeletonProps, 'variant' | 'children'> {
+  /** 按钮骨架尺寸，对齐 Button h-6/h-8/h-9，icon 为正方形。@default default */
+  size?: SkeletonButtonSize;
+  /** true 时撑满父容器宽度（icon 尺寸下不生效）。@default false */
+  block?: boolean;
+}
+
+function SkeletonButton({
+  className,
+  size = 'default',
+  block = false,
+  ...props
+}: SkeletonButtonProps) {
+  const effectiveBlock = size === 'icon' ? false : block;
+  return (
+    <Skeleton
+      data-slot="skeleton-button"
+      data-size={size}
+      variant="rectangular"
+      className={cn(
+        skeletonButtonVariants({ size, block: effectiveBlock }),
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── SkeletonInput ──────────────────────────────────────────────────────────
+
+const skeletonInputVariants = cva('rounded-md', {
+  variants: {
+    size: {
+      sm: 'h-6',
+      default: 'h-8',
+      lg: 'h-9',
+    },
+    block: {
+      true: 'w-full',
+      false: 'w-48',
+    },
+  },
+  defaultVariants: {
+    size: 'default',
+    block: true,
+  },
+});
+
+export type SkeletonInputSize = 'sm' | 'default' | 'lg';
+
+export interface SkeletonInputProps
+  extends Omit<SkeletonProps, 'variant' | 'children'> {
+  /** 输入框骨架尺寸，对齐 Input h-6/h-8/h-9。@default default */
+  size?: SkeletonInputSize;
+  /** true 撑满父容器宽度（默认）；false 时使用 w-48 默认宽度。@default true */
+  block?: boolean;
+}
+
+function SkeletonInput({
+  className,
+  size = 'default',
+  block = true,
+  ...props
+}: SkeletonInputProps) {
+  return (
+    <Skeleton
+      data-slot="skeleton-input"
+      data-size={size}
+      variant="rectangular"
+      className={cn(skeletonInputVariants({ size, block }), className)}
+      {...props}
+    />
+  );
+}
+
+// ─── SkeletonTitle ──────────────────────────────────────────────────────────
+
+export interface SkeletonTitleProps
+  extends Omit<SkeletonProps, 'variant' | 'children'> {
+  /** 标题宽度；不传时默认 1/3 容器宽度 */
+  width?: number | string;
+}
+
+function SkeletonTitle({ className, width, ...props }: SkeletonTitleProps) {
+  return (
+    <Skeleton
+      data-slot="skeleton-title"
+      variant="rectangular"
+      width={width}
+      className={cn(
+        'h-7 rounded-sm',
+        width === undefined && 'w-1/3',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── SkeletonParagraph ──────────────────────────────────────────────────────
+
+export type SkeletonParagraphWidth =
+  | number
+  | string
+  | Array<number | string>
+  | undefined;
+
+export interface SkeletonParagraphProps
+  extends Omit<React.ComponentProps<'div'>, 'children'> {
+  /** 行数。@default 3 */
+  rows?: number;
+  /**
+   * 每行宽度。
+   * - 单值：所有行同宽
+   * - 数组：按下标逐行覆盖，越界回退最后一项
+   * - 不传：除最后一行 60% 收窄外，其余 100%
+   */
+  width?: SkeletonParagraphWidth;
+  /** 动画类型，透传 base Skeleton。@default pulse */
+  animation?: SkeletonAnimation;
+  /** 加载条件渲染：true 显示骨架；false 直接渲染 children。@default true */
+  loading?: boolean;
+  /** 子内容；loading=false 时直接显示 */
+  children?: React.ReactNode;
+}
+
+function SkeletonParagraph({
+  className,
+  rows = 3,
+  width,
+  animation,
+  loading,
+  children,
+  ...props
+}: SkeletonParagraphProps) {
+  if (loading === false) return <>{children}</>;
+
+  const safeRows = Math.max(1, rows);
+
+  const resolveWidth = (i: number): number | string => {
+    if (Array.isArray(width)) {
+      return width[i] ?? width[width.length - 1] ?? '100%';
+    }
+    if (width !== undefined) return width;
+    return i === safeRows - 1 && safeRows > 1 ? '60%' : '100%';
+  };
+
+  return (
+    <div
+      data-slot="skeleton-paragraph"
+      className={cn('flex flex-col gap-2', className)}
+      {...props}
+    >
+      {Array.from({ length: safeRows }).map((_, i) => (
+        <Skeleton
+          key={i}
+          variant="rectangular"
+          animation={animation}
+          width={resolveWidth(i)}
+          className="h-4 rounded-sm"
+        />
+      ))}
+    </div>
+  );
+}
+
+export {
+  Skeleton,
+  SkeletonAvatar,
+  SkeletonImage,
+  SkeletonButton,
+  SkeletonInput,
+  SkeletonTitle,
+  SkeletonParagraph,
+  skeletonVariants,
+  skeletonAvatarVariants,
+  skeletonImageVariants,
+  skeletonButtonVariants,
+  skeletonInputVariants,
+};

package/src/components/skeleton/meta.md

@@ -0,0 +1,210 @@
+# Skeleton
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+骨架屏 Skeleton
+内容加载时的占位动画，提升感知加载速度。提供 base Skeleton 与 6 个子家族
+(Avatar / Image / Button / Input / Title / Paragraph) 用于一行替换占位。
+组合结构：Skeleton（base） · SkeletonAvatar / SkeletonImage / SkeletonButton /
+SkeletonInput / SkeletonTitle / SkeletonParagraph（独立子家族，可单独或组合使用）
+
+## 使用场景
+
+- 页面或区块初次加载时展示内容占位
+- 列表 / 卡片 / 详情数据加载中
+- 头像、图片、按钮、输入框等具体形态的加载占位
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `SkeletonVariant` | `rounded` | – | 形状变体：text 行高占位 / rectangular 矩形 / rounded 圆角矩形 / circular 圆形。 |
+| `animation` | `SkeletonAnimation` | `pulse` | – | 动画类型：pulse 呼吸 / none 静默；用户开启 reduced motion 时自动降级。 |
+| `width` | `number \| string` | – | – | 宽度，数字按 px 解析；与 className 同存时 inline style 优先 |
+| `height` | `number \| string` | – | – | 高度，数字按 px 解析 |
+| `loading` | `boolean` | – | – | 加载条件渲染：true 显示骨架；false 直接渲染 children（antd 风格）。@default true |
+| `asChild` | `boolean` | – | – | Slot 模式，将骨架样式应用到子元素上。@default false |
+| `children` | `React.ReactNode` | – | – | 子内容；loading=false 时直接显示 children |
+| `size` | `SkeletonAvatarSize \| number` | – | – | 头像尺寸；可传枚举或数字（数字按 px 当作宽高）。@default default |
+| `shape` | `'circle' \| 'square'` | – | – | 头像形状。@default circle |
+| `size` | `SkeletonImageSize` | – | – | 图片骨架尺寸。@default default |
+| `block` | `boolean` | – | – | true 时撑满父容器宽度并按 16:9 比例显示。@default false |
+| `icon` | `React.ReactNode` | – | – | 自定义占位图标节点；不传则使用 lucide ImageIcon |
+| `size` | `SkeletonButtonSize` | – | – | 按钮骨架尺寸，对齐 Button h-6/h-8/h-9，icon 为正方形。@default default |
+| `block` | `boolean` | – | – | true 时撑满父容器宽度（icon 尺寸下不生效）。@default false |
+| `size` | `SkeletonInputSize` | – | – | 输入框骨架尺寸，对齐 Input h-6/h-8/h-9。@default default |
+| `block` | `boolean` | – | – | true 撑满父容器宽度（默认）；false 时使用 w-48 默认宽度。@default true |
+| `width` | `number \| string` | – | – | 标题宽度；不传时默认 1/3 容器宽度 |
+| `rows` | `number` | – | – | 行数。@default 3 |
+| `width` | `SkeletonParagraphWidth` | – | – | 每行宽度。 - 单值：所有行同宽 - 数组：按下标逐行覆盖，越界回退最后一项 - 不传：除最后一行 60% 收窄外，其余 100% |
+| `animation` | `SkeletonAnimation` | – | – | 动画类型，透传 base Skeleton。@default pulse |
+| `loading` | `boolean` | – | – | 加载条件渲染：true 显示骨架；false 直接渲染 children。@default true |
+| `children` | `React.ReactNode` | – | – | 子内容；loading=false 时直接显示 |
+
+## 示例
+
+### Variants
+
+四种 variant 形状对照。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <div className="flex items-center gap-3">
+    <span className="w-24 text-muted-foreground">text</span>
+    <Skeleton variant="text" className="max-w-64" />
+  </div>
+  <div className="flex items-center gap-3">
+    <span className="w-24 text-muted-foreground">rectangular</span>
+    <Skeleton variant="rectangular" className="h-4 w-64" />
+  </div>
+  <div className="flex items-center gap-3">
+    <span className="w-24 text-muted-foreground">rounded</span>
+    <Skeleton variant="rounded" className="h-4 w-64" />
+  </div>
+  <div className="flex items-center gap-3">
+    <span className="w-24 text-muted-foreground">circular</span>
+    <Skeleton variant="circular" className="size-10" />
+  </div>
+</div>
+```
+
+### Animations
+
+pulse / none 两种动画对照。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <div className="flex items-center gap-3">
+    <span className="w-16 text-muted-foreground">pulse</span>
+    <Skeleton animation="pulse" className="h-4 w-64" />
+  </div>
+  <div className="flex items-center gap-3">
+    <span className="w-16 text-muted-foreground">none</span>
+    <Skeleton animation="none" className="h-4 w-64" />
+  </div>
+</div>
+```
+
+### WithDimensions
+
+通过 width / height props 直接传值（数字按 px 解析）。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <Skeleton width={240} height={16} />
+  <Skeleton width="50%" height={16} />
+  <Skeleton width={120} height={120} variant="circular" />
+</div>
+```
+
+### Avatar
+
+头像骨架：三档尺寸 + 两种形状。
+
+```tsx
+<div className="flex flex-col gap-4">
+  <div className="flex items-center gap-3">
+    <SkeletonAvatar size="sm" />
+    <SkeletonAvatar size="default" />
+    <SkeletonAvatar size="lg" />
+    <SkeletonAvatar size={56} />
+  </div>
+  <div className="flex items-center gap-3">
+    <SkeletonAvatar shape="square" size="sm" />
+    <SkeletonAvatar shape="square" size="default" />
+    <SkeletonAvatar shape="square" size="lg" />
+  </div>
+</div>
+```
+
+### Image
+
+图片骨架：三档尺寸 + block 自适应。
+
+```tsx
+<div className="flex flex-col gap-4">
+  <div className="flex items-end gap-3">
+    <SkeletonImage size="sm" />
+    <SkeletonImage size="default" />
+    <SkeletonImage size="lg" />
+  </div>
+  <SkeletonImage block />
+</div>
+```
+
+### ButtonSkeleton
+
+按钮骨架：四档尺寸 + block。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <div className="flex items-center gap-3">
+    <SkeletonButton size="sm" />
+    <SkeletonButton size="default" />
+    <SkeletonButton size="lg" />
+    <SkeletonButton size="icon" />
+  </div>
+  <SkeletonButton block />
+</div>
+```
+
+### Input
+
+输入框骨架：三档尺寸 + 非 block。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <SkeletonInput size="sm" />
+  <SkeletonInput size="default" />
+  <SkeletonInput size="lg" />
+  <SkeletonInput block={false} />
+</div>
+```
+
+### Title
+
+标题骨架：默认 1/3 容器宽，可自定义 width。
+
+```tsx
+<div className="flex flex-col gap-3">
+  <SkeletonTitle />
+  <SkeletonTitle width={200} />
+  <SkeletonTitle width="60%" />
+</div>
+```
+
+### Paragraph
+
+段落骨架：rows + width 数组逐行覆盖；不传 width 时末行 60% 收窄。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <SkeletonParagraph />
+  <SkeletonParagraph rows={5} />
+  <SkeletonParagraph rows={4} width={['100%', '90%', '80%', '40%']} />
+</div>
+```
+
+### CardComposition
+
+综合卡片占位：图片 + 头像 + 标题 + 段落。
+
+```tsx
+<div className="flex w-80 flex-col gap-4 rounded-md border border-border bg-card p-4">
+  <SkeletonImage block />
+  <div className="flex items-center gap-3">
+    <SkeletonAvatar />
+    <div className="flex flex-1 flex-col gap-2">
+      <SkeletonTitle width="50%" />
+      <Skeleton className="h-3 w-24" />
+    </div>
+  </div>
+  <SkeletonParagraph rows={3} />
+  <div className="flex items-center justify-end gap-2">
+    <SkeletonButton size="sm" />
+    <SkeletonButton size="sm" />
+  </div>
+</div>
+```