@neynar/ui 0.3.1 → 0.5.0

package/src/components/ui/item.tsx

@@ -1,462 +1,129 @@
-import * as React from "react"
-import { Slot } from "@radix-ui/react-slot"
-import { cva, type VariantProps } from "class-variance-authority"
+import * as React from "react";
+import { mergeProps } from "@base-ui/react/merge-props";
+import { useRender } from "@base-ui/react/use-render";
+import { cva, type VariantProps } from "class-variance-authority";
 
-import { cn } from "@/lib/utils"
-import { Separator } from "@/components/ui/separator"
+import { cn } from "@/lib/utils";
+import { Separator } from "@/components/ui/separator";
 
-/**
- * Props for ItemGroup component (Documentation only - NOT used in component implementation)
- *
- * Container component for grouping multiple Item components together with consistent
- * spacing and optional separators. Automatically adds ARIA list semantics.
- */
-type ItemGroupDocsProps = {
-  /** Additional CSS classes to apply to the group container */
-  className?: string
-  /** Item components to be grouped together */
-  children?: React.ReactNode
-} & React.HTMLAttributes<HTMLDivElement>
+type ItemGroupProps = React.ComponentProps<"div">;
 
 /**
- * ItemGroup - Container for grouping multiple Item components
- *
- * Provides a semantic list container for organizing related items with consistent
- * spacing and layout. Automatically applies role="list" for proper ARIA semantics.
- * Use with ItemSeparator to visually separate items within the group.
- *
- * @example
- * ```tsx
- * <ItemGroup>
- *   <Item>
- *     <ItemContent>
- *       <ItemTitle>First Item</ItemTitle>
- *     </ItemContent>
- *   </Item>
- *   <ItemSeparator />
- *   <Item>
- *     <ItemContent>
- *       <ItemTitle>Second Item</ItemTitle>
- *     </ItemContent>
- *   </Item>
- * </ItemGroup>
- * ```
- *
- * @example
- * ```tsx
- * // Notification list with grouped items
- * <ItemGroup>
- *   <Item variant="muted">
- *     <ItemMedia variant="icon">
- *       <Bell />
- *     </ItemMedia>
- *     <ItemContent>
- *       <ItemTitle>New notification</ItemTitle>
- *       <ItemDescription>You have a new message</ItemDescription>
- *     </ItemContent>
- *   </Item>
- *   <ItemSeparator />
- *   <Item>
- *     <ItemMedia variant="icon">
- *       <Clock />
- *     </ItemMedia>
- *     <ItemContent>
- *       <ItemTitle>Reminder</ItemTitle>
- *       <ItemDescription>Meeting in 30 minutes</ItemDescription>
- *     </ItemContent>
- *   </Item>
- * </ItemGroup>
- * ```
- *
- * @accessibility
- * - Automatically applies role="list" for screen readers
- * - Provides semantic structure for grouped content
- * - Works with keyboard navigation when items are interactive
- *
- * @see {@link Item} Individual item component
- * @see {@link ItemSeparator} Separator between items
- * @since 1.0.0
+ * Container for organizing related items in a vertical list.
+ * Automatically adjusts gap based on child item sizes.
  */
-function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
+function ItemGroup({ className, ...props }: ItemGroupProps) {
   return (
     <div
       role="list"
       data-slot="item-group"
-      className={cn("group/item-group flex flex-col", className)}
+      className={cn(
+        "gap-4 has-[[data-size=sm]]:gap-2.5 has-[[data-size=xs]]:gap-2 group/item-group flex w-full flex-col",
+        className,
+      )}
       {...props}
     />
-  )
+  );
 }
 
-/**
- * Props for ItemSeparator component (Documentation only - NOT used in component implementation)
- *
- * Horizontal separator for visually dividing items within an ItemGroup. Built on the
- * Separator primitive with optimized spacing for item layouts.
- */
-type ItemSeparatorDocsProps = {
-  /** Additional CSS classes to apply to the separator */
-  className?: string
-  /** Orientation of the separator @default "horizontal" */
-  orientation?: "horizontal" | "vertical"
-  /** Whether the separator is purely decorative @default true */
-  decorative?: boolean
-} & React.ComponentPropsWithoutRef<typeof Separator>
+type ItemSeparatorProps = React.ComponentProps<typeof Separator>;
 
 /**
- * ItemSeparator - Horizontal divider for separating items
- *
- * Provides a visual separator between items in an ItemGroup. Built on the Separator
- * component with optimized spacing (my-0) to work seamlessly with item layouts.
- * Always renders horizontally for consistent item list styling.
- *
- * @example
- * ```tsx
- * <ItemGroup>
- *   <Item>
- *     <ItemContent>
- *       <ItemTitle>First Item</ItemTitle>
- *     </ItemContent>
- *   </Item>
- *   <ItemSeparator />
- *   <Item>
- *     <ItemContent>
- *       <ItemTitle>Second Item</ItemTitle>
- *     </ItemContent>
- *   </Item>
- * </ItemGroup>
- * ```
- *
- * @example
- * ```tsx
- * // File list with separators
- * <ItemGroup>
- *   <Item asChild>
- *     <a href="#">
- *       <ItemMedia variant="icon">
- *         <FileText />
- *       </ItemMedia>
- *       <ItemContent>
- *         <ItemTitle>Document.pdf</ItemTitle>
- *       </ItemContent>
- *     </a>
- *   </Item>
- *   <ItemSeparator />
- *   <Item asChild>
- *     <a href="#">
- *       <ItemMedia variant="icon">
- *         <FileText />
- *       </ItemMedia>
- *       <ItemContent>
- *         <ItemTitle>Report.docx</ItemTitle>
- *       </ItemContent>
- *     </a>
- *   </Item>
- * </ItemGroup>
- * ```
- *
- * @accessibility
- * - Automatically marked as decorative (role="separator")
- * - Does not interfere with keyboard navigation
- * - Provides clear visual boundaries between interactive items
- *
- * @see {@link ItemGroup} Container for grouped items
- * @see {@link Separator} Base separator component
- * @since 1.0.0
+ * Horizontal separator for dividing items within an ItemGroup.
  */
-function ItemSeparator({
-  className,
-  ...props
-}: React.ComponentProps<typeof Separator>) {
+function ItemSeparator({ className, ...props }: ItemSeparatorProps) {
   return (
     <Separator
       data-slot="item-separator"
       orientation="horizontal"
-      className={cn("my-0", className)}
+      className={cn("my-2", className)}
       {...props}
     />
-  )
+  );
 }
 
-/**
- * Item variant styles using class-variance-authority
- *
- * @variant default - Transparent background for clean, minimal appearance
- * @variant outline - Border styling for emphasized boundaries
- * @variant muted - Subtle background for visual emphasis or grouping
- */
 const itemVariants = cva(
-  "group/item flex items-center border border-transparent text-sm rounded-md transition-colors [a]:hover:bg-accent/50 [a]:transition-colors duration-100 flex-wrap outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
+  "[a]:hover:bg-muted rounded-md border text-sm w-full group/item focus-visible:border-ring focus-visible:ring-ring/50 flex items-center flex-wrap outline-none transition-colors duration-100 focus-visible:ring-[3px] [a]:transition-colors",
   {
     variants: {
       variant: {
-        default: "bg-transparent",
+        default: "border-transparent",
         outline: "border-border",
-        muted: "bg-muted/50",
+        muted: "bg-muted/50 border-transparent",
       },
       size: {
-        default: "p-4 gap-4 ",
-        sm: "py-3 px-4 gap-2.5",
+        default: "gap-3.5 px-4 py-3.5",
+        sm: "gap-2.5 px-3 py-2.5",
+        xs: "gap-2 px-2.5 py-2 [[data-slot=dropdown-menu-content]_&]:p-0",
       },
     },
     defaultVariants: {
       variant: "default",
       size: "default",
     },
-  }
-)
+  },
+);
 
-/**
- * Props for Item component (Documentation only - NOT used in component implementation)
- *
- * Flexible container for displaying content with media, titles, descriptions, and actions.
- * Supports composition patterns via the asChild prop and multiple visual variants.
- */
-type ItemDocsProps = {
-  /** Visual style variant
-   * - "default": Transparent background for minimal appearance
-   * - "outline": Visible border for emphasis
-   * - "muted": Subtle background for visual grouping
-   * @default "default"
-   */
-  variant?: "default" | "outline" | "muted"
-  /** Size variant controlling padding and gap spacing
-   * - "default": Standard padding (p-4) with 4-unit gap
-   * - "sm": Compact padding (py-3 px-4) with 2.5-unit gap
-   * @default "default"
-   */
-  size?: "default" | "sm"
-  /**
-   * Render the Item as a child element instead of a div.
-   * Uses Radix UI Slot to merge props with the child element.
-   * Perfect for rendering items as links or buttons.
-   * @default false
-   */
-  asChild?: boolean
-  /** Additional CSS classes to apply */
-  className?: string
-  /** Content to display within the item */
-  children?: React.ReactNode
-} & React.HTMLAttributes<HTMLDivElement>
+type ItemProps = useRender.ComponentProps<"div"> &
+  VariantProps<typeof itemVariants>;
 
 /**
- * Item - Flexible container for displaying structured content
- *
- * A composable component for creating rich list items, cards, and data displays.
- * Built with a slot-based architecture allowing flexible combinations of media,
- * content, actions, headers, and footers. Supports rendering as any HTML element
- * via the asChild prop for semantic flexibility (e.g., links, buttons).
- *
- * @example
- * ```tsx
- * // Basic item with icon and content
- * <Item>
- *   <ItemMedia variant="icon">
- *     <FileText />
- *   </ItemMedia>
- *   <ItemContent>
- *     <ItemTitle>Document.pdf</ItemTitle>
- *     <ItemDescription>Last modified today</ItemDescription>
- *   </ItemContent>
- * </Item>
- * ```
- *
- * @example
- * ```tsx
- * // Item as a clickable link with asChild
- * <Item asChild>
- *   <a href="/dashboard">
- *     <ItemMedia variant="icon">
- *       <Home />
- *     </ItemMedia>
- *     <ItemContent>
- *       <ItemTitle>Dashboard</ItemTitle>
- *       <ItemDescription>View your account overview</ItemDescription>
- *     </ItemContent>
- *     <ItemActions>
- *       <ChevronRight />
- *     </ItemActions>
- *   </a>
- * </Item>
- * ```
- *
- * @example
- * ```tsx
- * // Rich item with header, footer, and actions
- * <Item variant="outline">
- *   <ItemMedia variant="image">
- *     <img src="/avatar.jpg" alt="User" />
- *   </ItemMedia>
- *   <ItemContent>
- *     <ItemHeader>
- *       <ItemTitle>John Doe</ItemTitle>
- *       <Badge>Pro</Badge>
- *     </ItemHeader>
- *     <ItemDescription>Product Manager</ItemDescription>
- *     <ItemFooter>
- *       <span className="text-xs">Last active 5m ago</span>
- *     </ItemFooter>
- *   </ItemContent>
- *   <ItemActions>
- *     <Button size="sm">Message</Button>
- *   </ItemActions>
- * </Item>
- * ```
- *
- * @example
- * ```tsx
- * // Small size variant for compact layouts
- * <Item size="sm">
- *   <ItemContent>
- *     <ItemTitle>Settings</ItemTitle>
- *   </ItemContent>
- *   <ItemActions>
- *     <ChevronRight className="size-4" />
- *   </ItemActions>
- * </Item>
- * ```
- *
- * @accessibility
- * - Supports keyboard navigation when interactive (via asChild with <a> or <button>)
- * - Focus visible ring appears on keyboard focus
- * - Proper semantic HTML when used with asChild prop
- * - Works with screen readers via proper content structure
- *
- * @see {@link ItemGroup} Container for grouping multiple items
- * @see {@link ItemMedia} Media slot for icons or images
- * @see {@link ItemContent} Main content container
- * @see {@link ItemTitle} Title text component
- * @see {@link ItemDescription} Description text component
- * @see {@link ItemActions} Actions slot for buttons or icons
- * @see {@link ItemHeader} Header layout for title and metadata
- * @see {@link ItemFooter} Footer layout for additional info
- * @since 1.0.0
+ * Flexible list item component for displaying structured content.
+ * Use `render` prop to customize the underlying element (e.g., `<a>`, `<button>`).
  */
 function Item({
   className,
   variant = "default",
   size = "default",
-  asChild = false,
+  render,
   ...props
-}: React.ComponentProps<"div"> &
-  VariantProps<typeof itemVariants> & { asChild?: boolean }) {
-  const Comp = asChild ? Slot : "div"
-  return (
-    <Comp
-      data-slot="item"
-      data-variant={variant}
-      data-size={size}
-      className={cn(itemVariants({ variant, size, className }))}
-      {...props}
-    />
-  )
+}: ItemProps) {
+  return useRender({
+    defaultTagName: "div",
+    props: mergeProps<"div">(
+      {
+        className: cn(itemVariants({ variant, size, className })),
+      },
+      props,
+    ),
+    render,
+    state: {
+      slot: "item",
+      variant,
+      size,
+    },
+  });
 }
 
-/**
- * ItemMedia variant styles using class-variance-authority
- *
- * @variant default - Transparent media container for raw content
- * @variant icon - Bordered container (8x8) with muted background, perfect for SVG icons
- * @variant image - Square container (10x10) with rounded corners for images or avatars
- */
 const itemMediaVariants = cva(
-  "flex shrink-0 items-center justify-center gap-2 group-has-[[data-slot=item-description]]/item:self-start [&_svg]:pointer-events-none group-has-[[data-slot=item-description]]/item:translate-y-0.5",
+  "gap-2 group-has-[[data-slot=item-description]]/item:translate-y-0.5 group-has-[[data-slot=item-description]]/item:self-start flex shrink-0 items-center justify-center [&_svg]:pointer-events-none",
   {
     variants: {
       variant: {
         default: "bg-transparent",
-        icon: "size-8 border rounded-sm bg-muted [&_svg:not([class*='size-'])]:size-4",
+        icon: "[&_svg:not([class*='size-'])]:size-4",
         image:
-          "size-10 rounded-sm overflow-hidden [&_img]:size-full [&_img]:object-cover",
+          "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",
       },
     },
     defaultVariants: {
       variant: "default",
     },
-  }
-)
+  },
+);
 
-/**
- * Props for ItemMedia component (Documentation only - NOT used in component implementation)
- *
- * Media container for displaying icons, images, or avatars at the start of an item.
- * Automatically aligns to the top when ItemDescription is present.
- */
-type ItemMediaDocsProps = {
-  /** Visual style variant for the media container
-   * - "default": Transparent container for custom content
-   * - "icon": 32px square with border and muted background (auto-sizes SVGs to 16px)
-   * - "image": 40px square with rounded corners and image cover styling
-   * @default "default"
-   */
-  variant?: "default" | "icon" | "image"
-  /** Additional CSS classes to apply */
-  className?: string
-  /** Media content (icon, image, or custom element) */
-  children?: React.ReactNode
-} & React.HTMLAttributes<HTMLDivElement>
+type ItemMediaProps = React.ComponentProps<"div"> &
+  VariantProps<typeof itemMediaVariants>;
 
 /**
- * ItemMedia - Media container for icons, images, or avatars
- *
- * Flexible media slot that appears at the start of an item. Supports three display
- * modes: transparent (default), bordered icon container, or image container with
- * object-fit styling. Automatically adjusts alignment when descriptions are present.
- *
- * @example
- * ```tsx
- * // Icon variant with automatic sizing
- * <Item>
- *   <ItemMedia variant="icon">
- *     <FileText />
- *   </ItemMedia>
- *   <ItemContent>
- *     <ItemTitle>Document</ItemTitle>
- *   </ItemContent>
- * </Item>
- * ```
- *
- * @example
- * ```tsx
- * // Image variant for avatars or thumbnails
- * <Item>
- *   <ItemMedia variant="image">
- *     <img src="/avatar.jpg" alt="User avatar" />
- *   </ItemMedia>
- *   <ItemContent>
- *     <ItemTitle>John Doe</ItemTitle>
- *     <ItemDescription>Product Manager</ItemDescription>
- *   </ItemContent>
- * </Item>
- * ```
- *
- * @example
- * ```tsx
- * // Default variant for custom content
- * <Item>
- *   <ItemMedia>
- *     <div className="size-12 rounded-full bg-gradient-to-br from-purple-400 to-pink-400" />
- *   </ItemMedia>
- *   <ItemContent>
- *     <ItemTitle>Custom Media</ItemTitle>
- *   </ItemContent>
- * </Item>
- * ```
- *
- * @accessibility
- * - SVG icons automatically marked as non-interactive (pointer-events-none)
- * - Images should include proper alt text for screen readers
- * - Container aligns to content start for better readability with multi-line text
- *
- * @see {@link Item} Parent container component
- * @see {@link ItemContent} Content container that pairs with media
- * @since 1.0.0
+ * Media container for icons, images, or avatars in an item.
+ * Automatically aligns with description text when present.
  */
 function ItemMedia({
   className,
   variant = "default",
   ...props
-}: React.ComponentProps<"div"> & VariantProps<typeof itemMediaVariants>) {
+}: ItemMediaProps) {
   return (
     <div
       data-slot="item-media"
@@ -464,471 +131,115 @@ function ItemMedia({
       className={cn(itemMediaVariants({ variant, className }))}
       {...props}
     />
-  )
+  );
 }
 
-/**
- * Props for ItemContent component (Documentation only - NOT used in component implementation)
- *
- * Main content container for item text and metadata. Grows to fill available space
- * and provides consistent vertical spacing between child elements.
- */
-type ItemContentDocsProps = {
-  /** Additional CSS classes to apply */
-  className?: string
-  /** Title, description, header, and footer components */
-  children?: React.ReactNode
-} & React.HTMLAttributes<HTMLDivElement>
+type ItemContentProps = React.ComponentProps<"div">;
 
 /**
- * ItemContent - Main content container for item text
- *
- * Flexible container that holds ItemTitle, ItemDescription, ItemHeader, and ItemFooter.
- * Automatically grows to fill available space (flex-1) and provides consistent gap
- * spacing (gap-1) between children. Multiple ItemContent containers can be used, with
- * subsequent ones not growing (flex-none).
- *
- * @example
- * ```tsx
- * <Item>
- *   <ItemContent>
- *     <ItemTitle>Document Name</ItemTitle>
- *     <ItemDescription>Additional details</ItemDescription>
- *   </ItemContent>
- * </Item>
- * ```
- *
- * @example
- * ```tsx
- * // Content with header and footer
- * <Item>
- *   <ItemMedia variant="icon">
- *     <FileText />
- *   </ItemMedia>
- *   <ItemContent>
- *     <ItemHeader>
- *       <ItemTitle>Meeting Notes</ItemTitle>
- *       <Badge>New</Badge>
- *     </ItemHeader>
- *     <ItemDescription>Notes from the team sync</ItemDescription>
- *     <ItemFooter>
- *       <span className="text-xs">Updated 5m ago</span>
- *     </ItemFooter>
- *   </ItemContent>
- * </Item>
- * ```
- *
- * @example
- * ```tsx
- * // Multiple content containers
- * <Item>
- *   <ItemContent>
- *     <ItemTitle>Primary Content</ItemTitle>
- *     <ItemDescription>Main information</ItemDescription>
- *   </ItemContent>
- *   <ItemContent>
- *     <span className="text-xs text-muted-foreground">Metadata</span>
- *   </ItemContent>
- * </Item>
- * ```
- *
- * @see {@link Item} Parent container
- * @see {@link ItemTitle} Title component
- * @see {@link ItemDescription} Description component
- * @see {@link ItemHeader} Header layout
- * @see {@link ItemFooter} Footer layout
- * @since 1.0.0
+ * Main content area for title and description.
+ * Flexes to fill available space.
  */
-function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
+function ItemContent({ className, ...props }: ItemContentProps) {
   return (
     <div
       data-slot="item-content"
       className={cn(
-        "flex flex-1 flex-col gap-1 [&+[data-slot=item-content]]:flex-none",
-        className
+        "gap-1 group-data-[size=xs]/item:gap-0 flex flex-1 flex-col [&+[data-slot=item-content]]:flex-none",
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
-/**
- * Props for ItemTitle component (Documentation only - NOT used in component implementation)
- *
- * Title text for an item. Medium font weight with snug line height for readability.
- */
-type ItemTitleDocsProps = {
-  /** Additional CSS classes to apply */
-  className?: string
-  /** Title text content */
-  children?: React.ReactNode
-} & React.HTMLAttributes<HTMLDivElement>
+type ItemTitleProps = React.ComponentProps<"div">;
 
 /**
- * ItemTitle - Title text for an item
- *
- * Displays the primary title or heading text for an item. Uses medium font weight
- * and tight line spacing for a prominent yet compact appearance. Inline-flex layout
- * allows badges or icons to be positioned next to the title.
- *
- * @example
- * ```tsx
- * <ItemContent>
- *   <ItemTitle>Document.pdf</ItemTitle>
- *   <ItemDescription>Last modified today</ItemDescription>
- * </ItemContent>
- * ```
- *
- * @example
- * ```tsx
- * // Title with inline badge
- * <ItemContent>
- *   <ItemTitle>
- *     Premium Feature
- *     <Badge variant="secondary">Pro</Badge>
- *   </ItemTitle>
- * </ItemContent>
- * ```
- *
- * @example
- * ```tsx
- * // Title with icon
- * <ItemContent>
- *   <ItemTitle>
- *     <Lock className="size-3" />
- *     Private Document
- *   </ItemTitle>
- * </ItemContent>
- * ```
- *
- * @see {@link ItemContent} Parent container
- * @see {@link ItemDescription} Paired description component
- * @since 1.0.0
+ * Title text with medium weight.
+ * Supports inline badges and icons.
  */
-function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
+function ItemTitle({ className, ...props }: ItemTitleProps) {
   return (
     <div
       data-slot="item-title"
       className={cn(
-        "flex w-fit items-center gap-2 text-sm leading-snug font-medium",
-        className
+        "gap-2 text-sm leading-snug font-medium underline-offset-4 line-clamp-1 flex w-fit items-center",
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
-/**
- * Props for ItemDescription component (Documentation only - NOT used in component implementation)
- *
- * Secondary descriptive text for an item. Muted color with 2-line clamping and
- * balanced text wrapping for optimal readability.
- */
-type ItemDescriptionDocsProps = {
-  /** Additional CSS classes to apply */
-  className?: string
-  /** Description text content (supports links) */
-  children?: React.ReactNode
-} & React.HTMLAttributes<HTMLParagraphElement>
+type ItemDescriptionProps = React.ComponentProps<"p">;
 
 /**
- * ItemDescription - Secondary descriptive text
- *
- * Displays supplementary information below the item title. Automatically limits
- * to 2 lines with text-balance for optimal wrapping. Includes special styling for
- * inline links with hover states. Text color is muted for visual hierarchy.
- *
- * @example
- * ```tsx
- * <ItemContent>
- *   <ItemTitle>Project Documentation</ItemTitle>
- *   <ItemDescription>
- *     Complete guide to project setup and configuration
- *   </ItemDescription>
- * </ItemContent>
- * ```
- *
- * @example
- * ```tsx
- * // Description with link
- * <ItemContent>
- *   <ItemTitle>Update Available</ItemTitle>
- *   <ItemDescription>
- *     A new version is available. <a href="#">Learn more</a>
- *   </ItemDescription>
- * </ItemContent>
- * ```
- *
- * @example
- * ```tsx
- * // Description with metadata
- * <ItemContent>
- *   <ItemTitle>Team Meeting</ItemTitle>
- *   <ItemDescription>
- *     Discuss Q4 planning and resource allocation
- *   </ItemDescription>
- * </ItemContent>
- * ```
- *
- * @accessibility
- * - Links within description are keyboard accessible
- * - Hover and focus states provide clear interaction feedback
- * - Text clamping ensures consistent layout without content overflow
- *
- * @see {@link ItemContent} Parent container
- * @see {@link ItemTitle} Paired title component
- * @since 1.0.0
+ * Secondary description text.
+ * Automatically truncates after 2 lines.
  */
-function ItemDescription({ className, ...props }: React.ComponentProps<"p">) {
+function ItemDescription({ className, ...props }: ItemDescriptionProps) {
   return (
     <p
       data-slot="item-description"
       className={cn(
-        "text-muted-foreground line-clamp-2 text-sm leading-normal font-normal text-balance",
-        "[&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4",
-        className
+        "text-muted-foreground text-left text-sm leading-normal group-data-[size=xs]/item:text-xs [&>a:hover]:text-primary line-clamp-2 font-normal [&>a]:underline [&>a]:underline-offset-4",
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
-/**
- * Props for ItemActions component (Documentation only - NOT used in component implementation)
- *
- * Container for action buttons, icons, or interactive elements positioned at the
- * end of an item. Provides consistent spacing between multiple actions.
- */
-type ItemActionsDocsProps = {
-  /** Additional CSS classes to apply */
-  className?: string
-  /** Button, icon, or interactive components */
-  children?: React.ReactNode
-} & React.HTMLAttributes<HTMLDivElement>
+type ItemActionsProps = React.ComponentProps<"div">;
 
 /**
- * ItemActions - Container for action buttons and icons
- *
- * Positioned at the end of an item for displaying interactive elements like buttons,
- * icons, or dropdown triggers. Flexbox layout with consistent gap spacing ensures
- * proper alignment of multiple actions.
- *
- * @example
- * ```tsx
- * <Item>
- *   <ItemContent>
- *     <ItemTitle>Document</ItemTitle>
- *   </ItemContent>
- *   <ItemActions>
- *     <Button variant="ghost" size="icon">
- *       <MoreVertical />
- *     </Button>
- *   </ItemActions>
- * </Item>
- * ```
- *
- * @example
- * ```tsx
- * // Multiple action buttons
- * <Item>
- *   <ItemContent>
- *     <ItemTitle>Task Item</ItemTitle>
- *   </ItemContent>
- *   <ItemActions>
- *     <Button variant="ghost" size="icon">
- *       <Star />
- *     </Button>
- *     <Button variant="ghost" size="icon">
- *       <CheckCircle2 />
- *     </Button>
- *     <Button variant="ghost" size="icon">
- *       <MoreVertical />
- *     </Button>
- *   </ItemActions>
- * </Item>
- * ```
- *
- * @example
- * ```tsx
- * // Text button with chevron
- * <Item>
- *   <ItemContent>
- *     <ItemTitle>Settings</ItemTitle>
- *   </ItemContent>
- *   <ItemActions>
- *     <ChevronRight className="size-4 text-muted-foreground" />
- *   </ItemActions>
- * </Item>
- * ```
- *
- * @accessibility
- * - Buttons should have proper aria-labels when using icon-only buttons
- * - Maintains keyboard navigation order
- * - Focus visible states on interactive elements
- *
- * @see {@link Item} Parent container
- * @see {@link ItemContent} Content container that pairs with actions
- * @since 1.0.0
+ * Container for action buttons or controls.
  */
-function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
+function ItemActions({ className, ...props }: ItemActionsProps) {
   return (
     <div
       data-slot="item-actions"
-      className={cn("flex items-center gap-2", className)}
+      className={cn("gap-2 flex items-center", className)}
       {...props}
     />
-  )
+  );
 }
 
-/**
- * Props for ItemHeader component (Documentation only - NOT used in component implementation)
- *
- * Layout container for positioning title and metadata side-by-side at full width
- * within an ItemContent. Typically contains ItemTitle and badges or status indicators.
- */
-type ItemHeaderDocsProps = {
-  /** Additional CSS classes to apply */
-  className?: string
-  /** Title and metadata components */
-  children?: React.ReactNode
-} & React.HTMLAttributes<HTMLDivElement>
+type ItemHeaderProps = React.ComponentProps<"div">;
 
 /**
- * ItemHeader - Layout container for title and metadata
- *
- * Creates a horizontal layout spanning the full width of ItemContent, positioning
- * content at the start and end (justify-between). Perfect for pairing ItemTitle with
- * badges, timestamps, or other metadata that should appear on the same line.
- *
- * @example
- * ```tsx
- * <ItemContent>
- *   <ItemHeader>
- *     <ItemTitle>Meeting Notes</ItemTitle>
- *     <Badge variant="secondary">New</Badge>
- *   </ItemHeader>
- *   <ItemDescription>Notes from team sync</ItemDescription>
- * </ItemContent>
- * ```
- *
- * @example
- * ```tsx
- * // Header with timestamp
- * <ItemContent>
- *   <ItemHeader>
- *     <ItemTitle>System Update</ItemTitle>
- *     <span className="text-xs text-muted-foreground">2h ago</span>
- *   </ItemHeader>
- * </ItemContent>
- * ```
- *
- * @example
- * ```tsx
- * // Header with multiple badges
- * <ItemContent>
- *   <ItemHeader>
- *     <ItemTitle>Premium Feature</ItemTitle>
- *     <div className="flex gap-1">
- *       <Badge>Pro</Badge>
- *       <Badge variant="secondary">Beta</Badge>
- *     </div>
- *   </ItemHeader>
- *   <ItemDescription>Advanced analytics and reporting</ItemDescription>
- * </ItemContent>
- * ```
- *
- * @see {@link ItemContent} Parent container
- * @see {@link ItemTitle} Title component typically used within header
- * @see {@link ItemFooter} Footer layout for bottom metadata
- * @since 1.0.0
+ * Full-width header section for complex item layouts.
  */
-function ItemHeader({ className, ...props }: 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
+        "gap-2 flex basis-full items-center justify-between",
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
-/**
- * Props for ItemFooter component (Documentation only - NOT used in component implementation)
- *
- * Layout container for positioning metadata and secondary information at the bottom
- * of an ItemContent. Spans full width with space-between layout.
- */
-type ItemFooterDocsProps = {
-  /** Additional CSS classes to apply */
-  className?: string
-  /** Metadata, timestamps, or secondary information */
-  children?: React.ReactNode
-} & React.HTMLAttributes<HTMLDivElement>
+type ItemFooterProps = React.ComponentProps<"div">;
 
 /**
- * ItemFooter - Layout container for bottom metadata
- *
- * Creates a horizontal layout at the bottom of ItemContent, spanning full width with
- * space-between distribution. Use for timestamps, file sizes, counts, or other
- * supplementary information that should appear below the main content.
- *
- * @example
- * ```tsx
- * <ItemContent>
- *   <ItemTitle>Document.pdf</ItemTitle>
- *   <ItemDescription>Project documentation</ItemDescription>
- *   <ItemFooter>
- *     <span className="text-xs text-muted-foreground">2.4 MB</span>
- *     <span className="text-xs text-muted-foreground">Modified today</span>
- *   </ItemFooter>
- * </ItemContent>
- * ```
- *
- * @example
- * ```tsx
- * // Footer with single metadata
- * <ItemContent>
- *   <ItemTitle>Team Meeting</ItemTitle>
- *   <ItemDescription>Discuss Q4 planning</ItemDescription>
- *   <ItemFooter>
- *     <span className="text-xs text-muted-foreground">
- *       Updated 5 minutes ago
- *     </span>
- *   </ItemFooter>
- * </ItemContent>
- * ```
- *
- * @example
- * ```tsx
- * // Footer with multiple metadata items
- * <ItemContent>
- *   <ItemTitle>Project Report</ItemTitle>
- *   <ItemDescription>Q4 Financial Analysis</ItemDescription>
- *   <ItemFooter>
- *     <span className="text-xs text-muted-foreground">5.8 MB</span>
- *     <span className="text-xs text-muted-foreground">Shared with 12</span>
- *   </ItemFooter>
- * </ItemContent>
- * ```
- *
- * @see {@link ItemContent} Parent container
- * @see {@link ItemHeader} Header layout for top metadata
- * @since 1.0.0
+ * Full-width footer section for additional information.
  */
-function ItemFooter({ className, ...props }: 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",
-        className
+        "gap-2 flex basis-full items-center justify-between",
+        className,
       )}
       {...props}
     />
-  )
+  );
 }
 
 export {
@@ -942,14 +253,14 @@ export {
   ItemDescription,
   ItemHeader,
   ItemFooter,
-  type ItemDocsProps,
-  type ItemMediaDocsProps,
-  type ItemContentDocsProps,
-  type ItemActionsDocsProps,
-  type ItemGroupDocsProps,
-  type ItemSeparatorDocsProps,
-  type ItemTitleDocsProps,
-  type ItemDescriptionDocsProps,
-  type ItemHeaderDocsProps,
-  type ItemFooterDocsProps,
-}
+  type ItemProps,
+  type ItemMediaProps,
+  type ItemContentProps,
+  type ItemActionsProps,
+  type ItemGroupProps,
+  type ItemSeparatorProps,
+  type ItemTitleProps,
+  type ItemDescriptionProps,
+  type ItemHeaderProps,
+  type ItemFooterProps,
+};