@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/item/index.tsx

@@ -0,0 +1,368 @@
+/**
+ * 列表项 Item
+ *
+ * 通用列表项组件，支持多种尺寸、变体与布局模式，可组合图标、媒体、文本、操作区与附加信息。
+ * 对齐 cloud-design List.Item + Antd v5 List.Item 能力集，按 shadcn v4 composable 理念实现。
+ *
+ * @when
+ * - 设置页的选项列表
+ * - 侧边栏菜单项
+ * - 数据列表的行项
+ * - 图文卡片（horizontal 布局）
+ * - 通知/消息列表
+ * - 带操作的资源列表
+ *
+ * 组合结构：ItemGroup [bordered] [divider] > ItemGroupHeader + Item* > ItemMedia + ItemContent (> ItemTitle + ItemDescription) + ItemExtra + ItemActions [separated] > ItemGroupFooter
+ */
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Slot } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+import { Separator } from '@/components/separator';
+
+// ─── ItemGroup ────────────────────────────────────────────────────────────────
+
+const itemGroupVariants = cva('flex w-full flex-col', {
+  variants: {
+    bordered: {
+      true: 'overflow-hidden rounded-md border border-border',
+      false: '',
+    },
+    divider: {
+      true: '[&>[data-slot=item]+[data-slot=item]]:border-t [&>[data-slot=item]+[data-slot=item]]:border-border',
+      false: 'gap-1',
+    },
+  },
+  defaultVariants: {
+    bordered: false,
+    divider: false,
+  },
+});
+
+export interface ItemGroupProps
+  extends React.ComponentProps<'div'>,
+    VariantProps<typeof itemGroupVariants> {}
+
+function ItemGroup({ className, bordered, divider, ...props }: ItemGroupProps) {
+  return (
+    <div
+      role="list"
+      data-slot="item-group"
+      data-bordered={bordered || undefined}
+      data-divider={divider || undefined}
+      className={cn(itemGroupVariants({ bordered, divider, className }))}
+      {...props}
+    />
+  );
+}
+
+// ─── ItemGroupHeader ──────────────────────────────────────────────────────────
+
+export interface ItemGroupHeaderProps extends React.ComponentProps<'div'> {}
+
+function ItemGroupHeader({ className, ...props }: ItemGroupHeaderProps) {
+  return (
+    <div
+      data-slot="item-group-header"
+      className={cn(
+        'flex items-center px-3 py-2.5 text-sm font-medium border-b border-border',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── ItemGroupFooter ──────────────────────────────────────────────────────────
+
+export interface ItemGroupFooterProps extends React.ComponentProps<'div'> {}
+
+function ItemGroupFooter({ className, ...props }: ItemGroupFooterProps) {
+  return (
+    <div
+      data-slot="item-group-footer"
+      className={cn(
+        'flex items-center px-3 py-2.5 text-xs text-muted-foreground border-t border-border',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── Item ─────────────────────────────────────────────────────────────────────
+
+const itemVariants = cva(
+  'group/item flex w-full items-center text-xs outline-none transition-colors duration-100 focus-visible:ring-1 focus-visible:ring-ring',
+  {
+    variants: {
+      variant: {
+        default: '',
+        outline: 'rounded-md border border-border focus-visible:border-ring',
+        muted: 'rounded-md bg-muted/50',
+      },
+      size: {
+        default: 'gap-3 px-3 py-3',
+        sm: 'gap-2.5 px-3 py-2.5',
+        xs: 'gap-2 px-2.5 py-2',
+      },
+      layout: {
+        vertical: 'flex-wrap',
+        horizontal: 'flex-nowrap',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+      layout: 'vertical',
+    },
+  },
+);
+
+export interface ItemProps
+  extends React.ComponentProps<'div'>,
+    VariantProps<typeof itemVariants> {
+  /** 使用 Slot 模式渲染子元素 */
+  asChild?: boolean;
+}
+
+function Item({
+  className,
+  variant = 'default',
+  size = 'default',
+  layout = 'vertical',
+  asChild = false,
+  ...props
+}: ItemProps) {
+  const Comp = asChild ? Slot.Root : 'div';
+  return (
+    <Comp
+      data-slot="item"
+      data-variant={variant}
+      data-size={size}
+      data-layout={layout}
+      className={cn(itemVariants({ variant, size, layout, className }))}
+      {...props}
+    />
+  );
+}
+
+// ─── ItemMedia ────────────────────────────────────────────────────────────────
+
+const itemMediaVariants = cva(
+  'flex shrink-0 items-center justify-center [&_svg]:pointer-events-none',
+  {
+    variants: {
+      variant: {
+        default: '',
+        icon: "[&_svg:not([class*='size-'])]:size-4",
+        image:
+          'size-10 overflow-hidden rounded-sm group-data-[size=sm]/item:size-8 group-data-[size=xs]/item:size-6 [&_img]:size-full [&_img]:object-cover',
+        cover:
+          'w-40 self-stretch overflow-hidden rounded-md group-data-[size=sm]/item:w-32 group-data-[size=xs]/item:w-24 [&_img]:size-full [&_img]:object-cover',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  },
+);
+
+export interface ItemMediaProps
+  extends React.ComponentProps<'div'>,
+    VariantProps<typeof itemMediaVariants> {}
+
+function ItemMedia({
+  className,
+  variant = 'default',
+  ...props
+}: ItemMediaProps) {
+  return (
+    <div
+      data-slot="item-media"
+      data-variant={variant}
+      className={cn(itemMediaVariants({ variant, className }))}
+      {...props}
+    />
+  );
+}
+
+// ─── ItemContent ──────────────────────────────────────────────────────────────
+
+export interface ItemContentProps extends React.ComponentProps<'div'> {}
+
+function ItemContent({ className, ...props }: ItemContentProps) {
+  return (
+    <div
+      data-slot="item-content"
+      className={cn('flex min-w-0 flex-1 flex-col gap-1', className)}
+      {...props}
+    />
+  );
+}
+
+// ─── ItemTitle ────────────────────────────────────────────────────────────────
+
+export interface ItemTitleProps extends React.ComponentProps<'div'> {}
+
+function ItemTitle({ className, ...props }: ItemTitleProps) {
+  return (
+    <div
+      data-slot="item-title"
+      className={cn(
+        'line-clamp-1 text-sm leading-snug font-medium [&>a]:text-primary [&>a]:no-underline [&>a:hover]:text-primary/80',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── ItemDescription ──────────────────────────────────────────────────────────
+
+export interface ItemDescriptionProps extends React.ComponentProps<'p'> {}
+
+function ItemDescription({ className, ...props }: ItemDescriptionProps) {
+  return (
+    <p
+      data-slot="item-description"
+      className={cn(
+        'line-clamp-2 text-xs leading-normal font-normal text-muted-foreground [&>a]:text-primary [&>a]:no-underline [&>a:hover]:text-primary/80',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── ItemExtra ────────────────────────────────────────────────────────────────
+
+export interface ItemExtraProps extends React.ComponentProps<'div'> {}
+
+function ItemExtra({ className, ...props }: ItemExtraProps) {
+  return (
+    <div
+      data-slot="item-extra"
+      className={cn(
+        'ml-auto shrink-0 text-xs text-muted-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── ItemActions ──────────────────────────────────────────────────────────────
+
+export interface ItemActionsProps extends React.ComponentProps<'div'> {
+  /** 子元素之间自动插入竖向分隔线 */
+  separated?: boolean;
+}
+
+function ItemActions({
+  className,
+  separated = false,
+  children,
+  ...props
+}: ItemActionsProps) {
+  const content = separated
+    ? React.Children.toArray(children).reduce<React.ReactNode[]>(
+        (acc, child, index) => {
+          if (index > 0) {
+            acc.push(
+              <Separator
+                key={`sep-${index}`}
+                orientation="vertical"
+                className="h-4"
+              />,
+            );
+          }
+          acc.push(child);
+          return acc;
+        },
+        [],
+      )
+    : children;
+
+  return (
+    <div
+      data-slot="item-actions"
+      className={cn('flex shrink-0 items-center gap-2', className)}
+      {...props}
+    >
+      {content}
+    </div>
+  );
+}
+
+// ─── ItemHeader ───────────────────────────────────────────────────────────────
+
+export interface ItemHeaderProps extends React.ComponentProps<'div'> {}
+
+function ItemHeader({ className, ...props }: ItemHeaderProps) {
+  return (
+    <div
+      data-slot="item-header"
+      className={cn(
+        'flex basis-full items-center justify-between gap-2',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── ItemFooter ───────────────────────────────────────────────────────────────
+
+export interface ItemFooterProps extends React.ComponentProps<'div'> {}
+
+function ItemFooter({ className, ...props }: ItemFooterProps) {
+  return (
+    <div
+      data-slot="item-footer"
+      className={cn(
+        'flex basis-full items-center justify-between gap-2 pt-2 text-xs text-muted-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+// ─── ItemSeparator ────────────────────────────────────────────────────────────
+
+export interface ItemSeparatorProps
+  extends React.ComponentProps<typeof Separator> {}
+
+function ItemSeparator({ className, ...props }: ItemSeparatorProps) {
+  return (
+    <Separator
+      data-slot="item-separator"
+      orientation="horizontal"
+      className={cn('', className)}
+      {...props}
+    />
+  );
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+export {
+  ItemGroup,
+  ItemGroupHeader,
+  ItemGroupFooter,
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription,
+  ItemExtra,
+  ItemActions,
+  ItemHeader,
+  ItemFooter,
+  ItemSeparator,
+  itemVariants,
+  itemGroupVariants,
+  itemMediaVariants,
+};