@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/descriptions/index.tsx

@@ -0,0 +1,535 @@
+/**
+ * 描述列表 Descriptions
+ *
+ * 以键值对形式展示实体属性，支持响应式列数、横/纵布局、边框矩阵、跨列与展开收起。
+ * 完全采用 shadcn 风格纯 composable slot —— 由 DescriptionsItem / DescriptionsLabel /
+ * DescriptionsContent 自由组合，label 与 content 都是 ReactNode 槽位，
+ * 不再提供 items 数据驱动 API；如需 label 带 tooltip 图标，直接在
+ * `<DescriptionsLabel>` 子树内拼装 `<Tooltip>` 即可。
+ *
+ * @when
+ * - 详情页展示实体属性（订单 / 用户 / 资源信息）
+ * - 设置页只读字段概览
+ * - Dialog / Drawer 中展示定宽信息
+ * - 列表行展开后的详情区
+ *
+ * 组合结构：Descriptions > DescriptionsHeader > DescriptionsTitle + DescriptionsExtra
+ *           Descriptions > DescriptionsBody > DescriptionsItem > DescriptionsLabel + DescriptionsContent
+ */
+
+'use client';
+
+import * as React from 'react';
+import { Slot } from 'radix-ui';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { ChevronDownIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { TooltipProvider } from '@/components/tooltip';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type DescriptionsBreakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+export type DescriptionsColumn =
+  | number
+  | Partial<Record<DescriptionsBreakpoint, number>>;
+
+export type DescriptionsLayout = 'horizontal' | 'vertical';
+export type DescriptionsSize = 'sm' | 'default';
+export type DescriptionsAlign = 'start' | 'center' | 'end';
+
+// ─── Column class 映射（静态写出便于 Tailwind 扫描） ───────────────────
+
+const COLUMN_BASE_CLASS: Record<number, string> = {
+  1: 'grid-cols-1',
+  2: 'grid-cols-2',
+  3: 'grid-cols-3',
+  4: 'grid-cols-4',
+  5: 'grid-cols-5',
+  6: 'grid-cols-6',
+};
+
+const COLUMN_BREAKPOINT_CLASS: Record<
+  Exclude<DescriptionsBreakpoint, 'xs'>,
+  Record<number, string>
+> = {
+  sm: {
+    1: 'sm:grid-cols-1',
+    2: 'sm:grid-cols-2',
+    3: 'sm:grid-cols-3',
+    4: 'sm:grid-cols-4',
+    5: 'sm:grid-cols-5',
+    6: 'sm:grid-cols-6',
+  },
+  md: {
+    1: 'md:grid-cols-1',
+    2: 'md:grid-cols-2',
+    3: 'md:grid-cols-3',
+    4: 'md:grid-cols-4',
+    5: 'md:grid-cols-5',
+    6: 'md:grid-cols-6',
+  },
+  lg: {
+    1: 'lg:grid-cols-1',
+    2: 'lg:grid-cols-2',
+    3: 'lg:grid-cols-3',
+    4: 'lg:grid-cols-4',
+    5: 'lg:grid-cols-5',
+    6: 'lg:grid-cols-6',
+  },
+  xl: {
+    1: 'xl:grid-cols-1',
+    2: 'xl:grid-cols-2',
+    3: 'xl:grid-cols-3',
+    4: 'xl:grid-cols-4',
+    5: 'xl:grid-cols-5',
+    6: 'xl:grid-cols-6',
+  },
+  '2xl': {
+    1: '2xl:grid-cols-1',
+    2: '2xl:grid-cols-2',
+    3: '2xl:grid-cols-3',
+    4: '2xl:grid-cols-4',
+    5: '2xl:grid-cols-5',
+    6: '2xl:grid-cols-6',
+  },
+};
+
+function clampCol(n: number): number {
+  if (Number.isFinite(n)) return Math.min(Math.max(Math.floor(n), 1), 6);
+  return 3;
+}
+
+function resolveColumnClass(column: DescriptionsColumn): string {
+  if (typeof column === 'number') {
+    return COLUMN_BASE_CLASS[clampCol(column)] ?? COLUMN_BASE_CLASS[3]!;
+  }
+  const xsCol = column.xs ?? column.sm ?? column.md ?? column.lg ?? 1;
+  const out: string[] = [
+    COLUMN_BASE_CLASS[clampCol(xsCol)] ?? COLUMN_BASE_CLASS[3]!,
+  ];
+  (['sm', 'md', 'lg', 'xl', '2xl'] as const).forEach((bp) => {
+    const v = column[bp];
+    if (v != null) {
+      const cls = COLUMN_BREAKPOINT_CLASS[bp][clampCol(v)];
+      if (cls) out.push(cls);
+    }
+  });
+  return out.filter(Boolean).join(' ');
+}
+
+// ─── 上下文：子组件感知容器配置 ─────────────────────────────────────────
+
+interface DescriptionsContextValue {
+  layout: DescriptionsLayout;
+  bordered: boolean;
+  size: DescriptionsSize;
+  colon: boolean;
+  labelStyle?: React.CSSProperties;
+  contentStyle?: React.CSSProperties;
+  labelWidth?: number | string;
+}
+
+const DescriptionsContext = React.createContext<DescriptionsContextValue>({
+  layout: 'horizontal',
+  bordered: false,
+  size: 'default',
+  colon: false,
+});
+
+// ─── cva ────────────────────────────────────────────────────────────────────
+
+const descriptionsVariants = cva('group/descriptions text-xs text-foreground', {
+  variants: {
+    bordered: {
+      true: 'overflow-hidden rounded-md border border-border',
+      false: '',
+    },
+  },
+  defaultVariants: {
+    bordered: false,
+  },
+});
+
+// ─── Descriptions（根） ────────────────────────────────────────────────────
+
+export interface DescriptionsProps
+  extends Omit<React.ComponentProps<'div'>, 'title'>,
+    VariantProps<typeof descriptionsVariants> {
+  /** 顶部标题。 */
+  title?: React.ReactNode;
+  /** 顶部右上槽（操作区）。 */
+  extra?: React.ReactNode;
+  /** 列数；支持响应式对象 `{ xs:1, sm:2, lg:3 }`。 @default 3 */
+  column?: DescriptionsColumn;
+  /** 布局方向。 @default 'horizontal' */
+  layout?: DescriptionsLayout;
+  /** 带边框矩阵。 @default false */
+  bordered?: boolean;
+  /** 尺寸：影响行高与内边距。 @default 'default' */
+  size?: DescriptionsSize;
+  /** horizontal 非 bordered 时是否在 label 后显示冒号。 @default false */
+  colon?: boolean;
+  /** label 默认样式（DescriptionsLabel 上的 style 优先级更高）。 */
+  labelStyle?: React.CSSProperties;
+  /** content 默认样式（DescriptionsContent 上的 style 优先级更高）。 */
+  contentStyle?: React.CSSProperties;
+  /** horizontal 非 bordered 时 label 列宽度。 */
+  labelWidth?: number | string;
+  /** 启用头部展开收起。 @default false */
+  collapsible?: boolean;
+  /** 受控展开状态。 */
+  open?: boolean;
+  /** 非受控初始展开状态。 @default true */
+  defaultOpen?: boolean;
+  /** 展开状态变化回调。 */
+  onOpenChange?: (open: boolean) => void;
+  /** Slot 模式：将容器渲染为子元素。 @default false */
+  asChild?: boolean;
+}
+
+function Descriptions({
+  className,
+  title,
+  extra,
+  column = 3,
+  layout = 'horizontal',
+  bordered = false,
+  size = 'default',
+  colon = false,
+  labelStyle,
+  contentStyle,
+  labelWidth,
+  collapsible = false,
+  open: openProp,
+  defaultOpen = true,
+  onOpenChange,
+  asChild = false,
+  children,
+  ...props
+}: DescriptionsProps) {
+  const Comp = asChild ? Slot.Root : 'div';
+
+  const [internalOpen, setInternalOpen] = React.useState(defaultOpen);
+  const open = openProp ?? internalOpen;
+  const handleOpenChange = (next: boolean) => {
+    if (openProp == null) setInternalOpen(next);
+    onOpenChange?.(next);
+  };
+
+  const bodyId = React.useId();
+
+  const ctx = React.useMemo<DescriptionsContextValue>(
+    () => ({
+      layout,
+      bordered,
+      size,
+      colon,
+      labelStyle,
+      contentStyle,
+      labelWidth,
+    }),
+    [layout, bordered, size, colon, labelStyle, contentStyle, labelWidth],
+  );
+
+  const showHeader = title != null || extra != null || collapsible;
+
+  return (
+    <TooltipProvider>
+      <Comp
+        data-slot="descriptions"
+        data-layout={layout}
+        data-size={size}
+        data-bordered={bordered ? 'true' : 'false'}
+        data-colon={colon ? 'true' : 'false'}
+        data-state={collapsible ? (open ? 'open' : 'closed') : undefined}
+        className={cn(descriptionsVariants({ bordered }), className)}
+        {...props}
+      >
+        {showHeader ? (
+          <DescriptionsHeader>
+            <DescriptionsTitle>
+              {collapsible ? (
+                <button
+                  type="button"
+                  aria-expanded={open}
+                  aria-controls={bodyId}
+                  onClick={() => handleOpenChange(!open)}
+                  className="inline-flex cursor-pointer items-center gap-1.5 rounded-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  data-slot="descriptions-trigger"
+                >
+                  <ChevronDownIcon
+                    className={cn(
+                      'size-4 shrink-0 text-muted-foreground transition-transform',
+                      !open && '-rotate-90',
+                    )}
+                  />
+                  <span className="min-w-0 truncate">{title}</span>
+                </button>
+              ) : title != null ? (
+                title
+              ) : null}
+            </DescriptionsTitle>
+            {extra != null ? (
+              <DescriptionsExtra>{extra}</DescriptionsExtra>
+            ) : null}
+          </DescriptionsHeader>
+        ) : null}
+        <DescriptionsContext.Provider value={ctx}>
+          <DescriptionsBody
+            id={bodyId}
+            column={column}
+            hidden={collapsible && !open ? true : undefined}
+          >
+            {children}
+          </DescriptionsBody>
+        </DescriptionsContext.Provider>
+      </Comp>
+    </TooltipProvider>
+  );
+}
+
+// ─── Header / Title / Extra ────────────────────────────────────────────────
+
+function DescriptionsHeader({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="descriptions-header"
+      className={cn(
+        'flex items-center justify-between gap-3',
+        // bordered: header 内嵌 + 灰底 + 下边框
+        'group-data-[bordered=true]/descriptions:border-b group-data-[bordered=true]/descriptions:border-border group-data-[bordered=true]/descriptions:bg-muted/30 group-data-[bordered=true]/descriptions:px-3 group-data-[bordered=true]/descriptions:py-2',
+        // bordered + sm
+        'group-data-[bordered=true]/descriptions:group-data-[size=sm]/descriptions:px-2 group-data-[bordered=true]/descriptions:group-data-[size=sm]/descriptions:py-1.5',
+        // 非 bordered: 顶部留白
+        'group-data-[bordered=false]/descriptions:mb-3',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function DescriptionsTitle({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="descriptions-title"
+      className={cn(
+        'min-w-0 flex-1 truncate text-sm font-semibold text-foreground group-data-[size=sm]/descriptions:text-xs',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function DescriptionsExtra({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="descriptions-extra"
+      className={cn('inline-flex shrink-0 items-center gap-2', className)}
+      {...props}
+    />
+  );
+}
+
+// ─── Body ──────────────────────────────────────────────────────────────────
+
+interface DescriptionsBodyProps extends React.ComponentProps<'div'> {
+  column?: DescriptionsColumn;
+}
+
+function DescriptionsBody({
+  className,
+  column = 3,
+  ...props
+}: DescriptionsBodyProps) {
+  const colClass = resolveColumnClass(column);
+  return (
+    <div
+      data-slot="descriptions-body"
+      className={cn(
+        'grid',
+        colClass,
+        // bordered 矩阵分隔：gap-px + bg-border，单元格之间产生 1px 灰线，
+        // 避免 divide-x/divide-y 与 header 的 border-b 叠加成 2px
+        'group-data-[bordered=true]/descriptions:gap-px group-data-[bordered=true]/descriptions:bg-border',
+        // 非 bordered horizontal 间距：gap-y 压缩，避免与 label/content min-h-6 叠加后过稀疏
+        'group-data-[bordered=false]/descriptions:group-data-[layout=horizontal]/descriptions:gap-x-6 group-data-[bordered=false]/descriptions:group-data-[layout=horizontal]/descriptions:gap-y-1.5',
+        // 非 bordered vertical 间距
+        'group-data-[bordered=false]/descriptions:group-data-[layout=vertical]/descriptions:gap-x-6 group-data-[bordered=false]/descriptions:group-data-[layout=vertical]/descriptions:gap-y-3',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── Item ──────────────────────────────────────────────────────────────────
+
+export interface DescriptionsItemProps
+  extends Omit<React.ComponentProps<'div'>, 'title'> {
+  /** 跨列数。 */
+  span?: number;
+  /** @deprecated 兼容旧字段，等价 span。 */
+  colSpan?: number;
+  /** 行内对齐方式。 @default 'start' */
+  align?: DescriptionsAlign;
+}
+
+function DescriptionsItem({
+  className,
+  span,
+  colSpan,
+  align = 'start',
+  style,
+  children,
+  ...props
+}: DescriptionsItemProps) {
+  const ctx = React.useContext(DescriptionsContext);
+  const finalSpan = span ?? colSpan;
+  const horizontal = ctx.layout === 'horizontal';
+
+  const itemStyle: React.CSSProperties = {
+    ...style,
+    ...(finalSpan && finalSpan > 1
+      ? { gridColumn: `span ${finalSpan} / span ${finalSpan}` }
+      : {}),
+  };
+
+  return (
+    <div
+      data-slot="descriptions-item"
+      data-align={align}
+      data-span={finalSpan ?? undefined}
+      className={cn(
+        'min-w-0',
+        // 布局：水平 vs 垂直
+        horizontal ? 'flex' : 'flex flex-col',
+        // bordered 单元格背景：盖住 body 的 bg-border，仅在 gap 处露出 1px 灰线
+        ctx.bordered && 'bg-background',
+        // 非 bordered + horizontal：label 与 content 间留 gap
+        !ctx.bordered && horizontal && 'gap-2',
+        !ctx.bordered && !horizontal && 'gap-1',
+        // 对齐
+        align === 'start' && (horizontal ? 'items-start' : 'items-stretch'),
+        align === 'center' && 'items-center',
+        align === 'end' && (horizontal ? 'items-end' : 'items-stretch'),
+        className,
+      )}
+      style={itemStyle}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+// ─── Label ─────────────────────────────────────────────────────────────────
+
+function DescriptionsLabel({
+  className,
+  style,
+  children,
+  ...props
+}: React.ComponentProps<'div'>) {
+  const ctx = React.useContext(DescriptionsContext);
+  const horizontal = ctx.layout === 'horizontal';
+  const showColon = ctx.colon && horizontal && !ctx.bordered;
+
+  const mergedStyle: React.CSSProperties = {
+    ...ctx.labelStyle,
+    ...(horizontal && !ctx.bordered && ctx.labelWidth != null
+      ? { width: ctx.labelWidth, minWidth: ctx.labelWidth }
+      : {}),
+    ...style,
+  };
+
+  return (
+    <div
+      data-slot="descriptions-label"
+      className={cn(
+        'inline-flex shrink-0 items-center gap-1 text-muted-foreground',
+        // bordered + horizontal: label 列灰底 + 固定宽
+        ctx.bordered &&
+          horizontal &&
+          'w-32 self-stretch border-r border-border bg-muted/30 px-3 py-2',
+        // bordered + vertical: label 在上 + 灰底
+        ctx.bordered &&
+          !horizontal &&
+          'w-full border-b border-border bg-muted/30 px-3 py-2',
+        // bordered + sm
+        ctx.bordered && ctx.size === 'sm' && 'px-2 py-1.5',
+        // 非 bordered + horizontal: 兜底最小宽 + min-h-6 高度对齐行内控件
+        // —— label 本身取文本行高（约 12px font × 1.5 ≈ 18px），与 content 中 24px 的 sm Button / Tag 顶对齐会产生
+        // 基线偏误；强制 min-h-6 + inline-flex items-center 后，label 框同样 24px，文字垂直居中，与
+        // 控件内文字基线自然对齐。如 content 是 h-8 / h-10 等更高控件，在 <DescriptionsItem align="center"> 带动。
+        !ctx.bordered && horizontal && 'min-w-24 min-h-6',
+        className,
+      )}
+      {...props}
+      style={mergedStyle}
+    >
+      {children}
+      {showColon ? (
+        <span aria-hidden="true" className="text-muted-foreground">
+          ：
+        </span>
+      ) : null}
+    </div>
+  );
+}
+
+// ─── Content ───────────────────────────────────────────────────────────────
+
+function DescriptionsContent({
+  className,
+  style,
+  ...props
+}: React.ComponentProps<'div'>) {
+  const ctx = React.useContext(DescriptionsContext);
+  const horizontal = ctx.layout === 'horizontal';
+  const mergedStyle: React.CSSProperties = {
+    ...ctx.contentStyle,
+    ...style,
+  };
+  return (
+    <div
+      data-slot="descriptions-content"
+      className={cn(
+        'min-w-0 flex-1 break-words text-foreground',
+        // 非 bordered + horizontal: 与 label 同高 24px + 垂直居中，使纯文字 content 与
+        // label 、sm Button / Tag 等 24px 控件基线自然对齐。多行长文本会将整体
+        // 拉高，此时让内容居中，若需顶对齐多行可用 <DescriptionsItem align="start"> + 手写 self-start。
+        !ctx.bordered && horizontal && 'flex min-h-6 items-center',
+        ctx.bordered && 'px-3 py-2',
+        ctx.bordered && ctx.size === 'sm' && 'px-2 py-1.5',
+        className,
+      )}
+      {...props}
+      style={mergedStyle}
+    />
+  );
+}
+
+export {
+  Descriptions,
+  DescriptionsHeader,
+  DescriptionsTitle,
+  DescriptionsExtra,
+  DescriptionsBody,
+  DescriptionsItem,
+  DescriptionsLabel,
+  DescriptionsContent,
+  descriptionsVariants,
+};

package/src/components/descriptions/meta.md

@@ -0,0 +1,104 @@
+# Descriptions
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+描述列表 Descriptions
+以键值对形式展示实体属性，支持响应式列数、横/纵布局、边框矩阵、跨列与展开收起。
+完全采用 shadcn 风格纯 composable slot —— 由 DescriptionsItem / DescriptionsLabel /
+DescriptionsContent 自由组合，label 与 content 都是 ReactNode 槽位，
+不再提供 items 数据驱动 API；如需 label 带 tooltip 图标，直接在
+`<DescriptionsLabel>` 子树内拼装 `<Tooltip>` 即可。
+
+## 使用场景
+
+- 详情页展示实体属性（订单 / 用户 / 资源信息）
+- 设置页只读字段概览
+- Dialog / Drawer 中展示定宽信息
+- 列表行展开后的详情区
+- 组合结构：Descriptions > DescriptionsHeader > DescriptionsTitle + DescriptionsExtra
+- Descriptions > DescriptionsBody > DescriptionsItem > DescriptionsLabel + DescriptionsContent
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `title` | `React.ReactNode` | – | – | 顶部标题。 |
+| `extra` | `React.ReactNode` | – | – | 顶部右上槽（操作区）。 |
+| `column` | `DescriptionsColumn` | `3` | – | 列数；支持响应式对象 `{ xs:1, sm:2, lg:3 }`。 |
+| `layout` | `DescriptionsLayout` | `'horizontal'` | – | 布局方向。 |
+| `bordered` | `boolean` | `false` | – | 带边框矩阵。 |
+| `size` | `DescriptionsSize` | `'default'` | – | 尺寸：影响行高与内边距。 |
+| `colon` | `boolean` | `false` | – | horizontal 非 bordered 时是否在 label 后显示冒号。 |
+| `labelStyle` | `React.CSSProperties` | – | – | label 默认样式（DescriptionsLabel 上的 style 优先级更高）。 |
+| `contentStyle` | `React.CSSProperties` | – | – | content 默认样式（DescriptionsContent 上的 style 优先级更高）。 |
+| `labelWidth` | `number \| string` | – | – | horizontal 非 bordered 时 label 列宽度。 |
+| `collapsible` | `boolean` | `false` | – | 启用头部展开收起。 |
+| `open` | `boolean` | – | – | 受控展开状态。 |
+| `defaultOpen` | `boolean` | `true` | – | 非受控初始展开状态。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 展开状态变化回调。 |
+| `asChild` | `boolean` | `false` | – | Slot 模式：将容器渲染为子元素。 |
+| `span` | `number` | – | – | 跨列数。 |
+| `colSpan` | `number` | – | – | – |
+| `align` | `DescriptionsAlign` | `'start'` | – | 行内对齐方式。 |
+
+## 示例
+
+### Sizes
+
+不同尺寸：sm / default 对比。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <Descriptions title="default 尺寸" bordered column={2}>
+    <DescriptionsItem>
+      <DescriptionsLabel>名称</DescriptionsLabel>
+      <DescriptionsContent>evo</DescriptionsContent>
+    </DescriptionsItem>
+    <DescriptionsItem>
+      <DescriptionsLabel>版本</DescriptionsLabel>
+      <DescriptionsContent>v0.8</DescriptionsContent>
+    </DescriptionsItem>
+  </Descriptions>
+  <Descriptions title="sm 尺寸" bordered size="sm" column={2}>
+    <DescriptionsItem>
+      <DescriptionsLabel>名称</DescriptionsLabel>
+      <DescriptionsContent>evo</DescriptionsContent>
+    </DescriptionsItem>
+    <DescriptionsItem>
+      <DescriptionsLabel>版本</DescriptionsLabel>
+      <DescriptionsContent>v0.8</DescriptionsContent>
+    </DescriptionsItem>
+  </Descriptions>
+</div>
+```
+
+### Colon
+
+冒号开关：默认不带冒号，需要时显式 `colon` 开启。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <Descriptions title="默认不带冒号" column={2}>
+    <DescriptionsItem>
+      <DescriptionsLabel>名称</DescriptionsLabel>
+      <DescriptionsContent>evo</DescriptionsContent>
+    </DescriptionsItem>
+    <DescriptionsItem>
+      <DescriptionsLabel>版本</DescriptionsLabel>
+      <DescriptionsContent>v0.8</DescriptionsContent>
+    </DescriptionsItem>
+  </Descriptions>
+  <Descriptions title="显式开启冒号" colon column={2}>
+    <DescriptionsItem>
+      <DescriptionsLabel>名称</DescriptionsLabel>
+      <DescriptionsContent>evo</DescriptionsContent>
+    </DescriptionsItem>
+    <DescriptionsItem>
+      <DescriptionsLabel>版本</DescriptionsLabel>
+      <DescriptionsContent>v0.8</DescriptionsContent>
+    </DescriptionsItem>
+  </Descriptions>
+</div>
+```