@neynar/ui 0.2.1 → 0.3.1

package/src/components/ui/item.tsx

@@ -0,0 +1,955 @@
+import * as React from "react"
+import { Slot } from "@radix-ui/react-slot"
+import { cva, type VariantProps } from "class-variance-authority"
+
+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>
+
+/**
+ * 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
+ */
+function ItemGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      role="list"
+      data-slot="item-group"
+      className={cn("group/item-group flex 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>
+
+/**
+ * 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
+ */
+function ItemSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof Separator>) {
+  return (
+    <Separator
+      data-slot="item-separator"
+      orientation="horizontal"
+      className={cn("my-0", 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]",
+  {
+    variants: {
+      variant: {
+        default: "bg-transparent",
+        outline: "border-border",
+        muted: "bg-muted/50",
+      },
+      size: {
+        default: "p-4 gap-4 ",
+        sm: "py-3 px-4 gap-2.5",
+      },
+    },
+    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>
+
+/**
+ * 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
+ */
+function Item({
+  className,
+  variant = "default",
+  size = "default",
+  asChild = false,
+  ...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}
+    />
+  )
+}
+
+/**
+ * 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",
+  {
+    variants: {
+      variant: {
+        default: "bg-transparent",
+        icon: "size-8 border rounded-sm bg-muted [&_svg:not([class*='size-'])]:size-4",
+        image:
+          "size-10 rounded-sm overflow-hidden [&_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>
+
+/**
+ * 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
+ */
+function ItemMedia({
+  className,
+  variant = "default",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof itemMediaVariants>) {
+  return (
+    <div
+      data-slot="item-media"
+      data-variant={variant}
+      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>
+
+/**
+ * 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
+ */
+function ItemContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="item-content"
+      className={cn(
+        "flex flex-1 flex-col gap-1 [&+[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>
+
+/**
+ * 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
+ */
+function ItemTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="item-title"
+      className={cn(
+        "flex w-fit items-center gap-2 text-sm leading-snug font-medium",
+        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>
+
+/**
+ * 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
+ */
+function ItemDescription({ className, ...props }: React.ComponentProps<"p">) {
+  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
+      )}
+      {...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>
+
+/**
+ * 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
+ */
+function ItemActions({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="item-actions"
+      className={cn("flex items-center gap-2", 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>
+
+/**
+ * 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
+ */
+function ItemHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="item-header"
+      className={cn(
+        "flex basis-full items-center justify-between gap-2",
+        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>
+
+/**
+ * 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
+ */
+function ItemFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="item-footer"
+      className={cn(
+        "flex basis-full items-center justify-between gap-2",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Item,
+  ItemMedia,
+  ItemContent,
+  ItemActions,
+  ItemGroup,
+  ItemSeparator,
+  ItemTitle,
+  ItemDescription,
+  ItemHeader,
+  ItemFooter,
+  type ItemDocsProps,
+  type ItemMediaDocsProps,
+  type ItemContentDocsProps,
+  type ItemActionsDocsProps,
+  type ItemGroupDocsProps,
+  type ItemSeparatorDocsProps,
+  type ItemTitleDocsProps,
+  type ItemDescriptionDocsProps,
+  type ItemHeaderDocsProps,
+  type ItemFooterDocsProps,
+}