@neynar/ui 0.1.1

package/src/components/ui/card.tsx

@@ -0,0 +1,447 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Card - A flexible container component for grouping related content
+ *
+ * Cards are surfaces that display content and actions on a single topic.
+ * They should be easy to scan for relevant and actionable information.
+ * Cards support composition through multiple sub-components and can be
+ * customized with various layouts and styling patterns.
+ *
+ * Based on the shadcn/ui Card component, this implementation provides:
+ * - Flexible composition through sub-components
+ * - Semantic HTML structure for accessibility
+ * - Consistent spacing and visual hierarchy
+ * - Support for interactive elements and actions
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic card with header and content
+ * <Card>
+ *   <CardHeader>
+ *     <CardTitle>Card Title</CardTitle>
+ *     <CardDescription>Card description goes here</CardDescription>
+ *   </CardHeader>
+ *   <CardContent>
+ *     <p>Card content goes here</p>
+ *   </CardContent>
+ * </Card>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Card with action button in header
+ * <Card>
+ *   <CardHeader>
+ *     <CardTitle>Settings</CardTitle>
+ *     <CardAction>
+ *       <Button variant="ghost" size="icon">
+ *         <Settings />
+ *       </Button>
+ *     </CardAction>
+ *   </CardHeader>
+ *   <CardContent>
+ *     <p>Manage your settings</p>
+ *   </CardContent>
+ *   <CardFooter>
+ *     <Button>Save Changes</Button>
+ *   </CardFooter>
+ * </Card>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Minimal card with only content
+ * <Card>
+ *   <CardContent>
+ *     <p>Simple card content without header or footer</p>
+ *   </CardContent>
+ * </Card>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Product card with custom styling
+ * <Card className="w-80 hover:shadow-lg transition-shadow">
+ *   <CardHeader>
+ *     <div className="aspect-video bg-muted rounded-lg mb-4" />
+ *     <CardTitle>Product Name</CardTitle>
+ *     <CardDescription>Product description</CardDescription>
+ *     <CardAction>
+ *       <Badge variant="secondary">New</Badge>
+ *     </CardAction>
+ *   </CardHeader>
+ *   <CardContent>
+ *     <div className="flex items-center justify-between">
+ *       <span className="text-2xl font-bold">$299</span>
+ *       <span className="text-sm text-muted-foreground line-through">$399</span>
+ *     </div>
+ *   </CardContent>
+ *   <CardFooter className="gap-2">
+ *     <Button className="flex-1">Add to Cart</Button>
+ *     <Button size="icon" variant="outline">
+ *       <Heart className="size-4" />
+ *     </Button>
+ *   </CardFooter>
+ * </Card>
+ * ```
+ *
+ * @accessibility
+ * - Uses semantic HTML structure with proper div elements
+ * - Supports keyboard navigation for interactive elements within
+ * - Proper heading hierarchy when using CardTitle
+ * - Screen reader friendly with clear content structure
+ * - Focus management handled by interactive child components
+ *
+ * @param {string} [className] - Additional CSS classes to apply to the card
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Standard HTML div attributes
+ *
+ * @see {@link CardHeader} - Card header container with grid layout support
+ * @see {@link CardTitle} - Card title component for main headings
+ * @see {@link CardDescription} - Card description component for supplementary text
+ * @see {@link CardAction} - Card action container for header buttons/controls
+ * @see {@link CardContent} - Card content container for main body content
+ * @see {@link CardFooter} - Card footer container for actions and supplementary info
+ * @see {@link https://ui.shadcn.com/docs/components/card} - shadcn/ui Card documentation
+ * @since 1.0.0
+ */
+function Card({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card"
+      className={cn(
+        "bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * CardHeader - Container for card header content
+ *
+ * Groups the card title, description, and optional action button.
+ * Automatically handles grid layout when CardAction is present, positioning
+ * the action to the right while allowing title and description to span
+ * the remaining space.
+ *
+ * Uses CSS Grid with container queries for responsive behavior:
+ * - Default: Single column layout for title and description
+ * - With CardAction: Two-column grid with action positioned top-right
+ * - Auto-adjusts spacing with gap utilities
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic header with title and description
+ * <CardHeader>
+ *   <CardTitle>Dashboard Overview</CardTitle>
+ *   <CardDescription>View your analytics and metrics</CardDescription>
+ * </CardHeader>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Header with action button
+ * <CardHeader>
+ *   <CardTitle>Settings</CardTitle>
+ *   <CardDescription>Manage your preferences</CardDescription>
+ *   <CardAction>
+ *     <Button variant="ghost" size="icon">
+ *       <MoreHorizontal className="size-4" />
+ *     </Button>
+ *   </CardAction>
+ * </CardHeader>
+ * ```
+ *
+ * @accessibility
+ * - Maintains proper heading structure with CardTitle
+ * - Supports responsive layout with container queries
+ * - Grid layout preserves reading order for screen readers
+ * - Action buttons maintain focus order
+ *
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Standard HTML div attributes
+ * @since 1.0.0
+ */
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-1.5 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * CardTitle - The main title of a card
+ *
+ * Renders the primary heading for a card. Should be used within CardHeader
+ * to maintain proper semantic structure and visual hierarchy. Uses semibold
+ * font weight and leading-none for compact appearance.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CardTitle>Dashboard Overview</CardTitle>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom styling
+ * <CardTitle className="text-lg text-primary">
+ *   Featured Product
+ * </CardTitle>
+ * ```
+ *
+ * @accessibility
+ * - Acts as the primary heading for the card content
+ * - Should maintain logical heading hierarchy in the document
+ * - Screen readers will identify this as the card's main topic
+ *
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Standard HTML div attributes
+ * @since 1.0.0
+ */
+function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn("leading-none font-semibold", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * CardDescription - Supplementary description text for a card
+ *
+ * Provides additional context or details about the card content.
+ * Styled with muted foreground color and smaller text size to create
+ * visual hierarchy below the CardTitle.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CardDescription>
+ *   View and manage your dashboard settings
+ * </CardDescription>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multi-line description
+ * <CardDescription>
+ *   This card contains important information about your account.
+ *   Review the details and take action if needed.
+ * </CardDescription>
+ * ```
+ *
+ * @accessibility
+ * - Provides context for screen readers
+ * - Uses muted color that maintains sufficient contrast
+ * - Should be descriptive and concise
+ *
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Standard HTML div attributes
+ * @since 1.0.0
+ */
+function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-muted-foreground text-sm", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * CardAction - Container for card header actions
+ *
+ * Positioned to the right of the card header using CSS Grid positioning.
+ * Typically contains icon buttons, badges, or dropdown menus for card-specific
+ * actions. Automatically positioned when used within CardHeader.
+ *
+ * Grid positioning:
+ * - `col-start-2`: Places in second column
+ * - `row-span-2`: Spans both title and description rows
+ * - `row-start-1`: Starts from first row
+ * - `self-start justify-self-end`: Aligns to top-right
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CardAction>
+ *   <Button variant="ghost" size="icon">
+ *     <MoreHorizontal className="size-4" />
+ *   </Button>
+ * </CardAction>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With badge
+ * <CardAction>
+ *   <Badge variant="secondary">New</Badge>
+ * </CardAction>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With dropdown menu
+ * <CardAction>
+ *   <DropdownMenu>
+ *     <DropdownMenuTrigger asChild>
+ *       <Button variant="ghost" size="icon">
+ *         <MoreHorizontal className="size-4" />
+ *       </Button>
+ *     </DropdownMenuTrigger>
+ *     <DropdownMenuContent>
+ *       <DropdownMenuItem>Edit</DropdownMenuItem>
+ *       <DropdownMenuItem>Delete</DropdownMenuItem>
+ *     </DropdownMenuContent>
+ *   </DropdownMenu>
+ * </CardAction>
+ * ```
+ *
+ * @accessibility
+ * - Interactive elements should have appropriate labels
+ * - Maintains logical tab order
+ * - Icon-only buttons should include aria-label
+ *
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Standard HTML div attributes
+ * @since 1.0.0
+ */
+function CardAction({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn(
+        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * CardContent - Main content area of a card
+ *
+ * Contains the primary content for the card. Automatically applies
+ * horizontal padding to maintain consistent spacing with other card sections.
+ * Can contain any type of content including text, images, forms, or other
+ * components.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <CardContent>
+ *   <p>Your main content goes here.</p>
+ * </CardContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom spacing
+ * <CardContent className="py-4">
+ *   <div className="space-y-4">
+ *     <p>Multiple content elements</p>
+ *     <Button>Action button</Button>
+ *   </div>
+ * </CardContent>
+ * ```
+ *
+ * @accessibility
+ * - Contains the main content that screen readers will focus on
+ * - Should maintain logical content structure
+ * - Interactive elements should have proper focus management
+ *
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Standard HTML div attributes
+ * @since 1.0.0
+ */
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-6", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * CardFooter - Footer area of a card, typically for actions
+ *
+ * Positioned at the bottom of the card and commonly used for action buttons,
+ * supplementary information, or navigation elements. Uses flexbox layout
+ * with automatic alignment of items. Can be styled with border-top when
+ * visual separation from content is needed.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Basic footer with actions
+ * <CardFooter>
+ *   <Button variant="outline">Cancel</Button>
+ *   <Button>Save</Button>
+ * </CardFooter>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Footer with gap for better spacing
+ * <CardFooter className="gap-2">
+ *   <Button variant="outline" className="flex-1">Cancel</Button>
+ *   <Button className="flex-1">Confirm</Button>
+ * </CardFooter>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Footer with supplementary info
+ * <CardFooter className="justify-between">
+ *   <span className="text-sm text-muted-foreground">Last updated 2 days ago</span>
+ *   <Button size="sm">Edit</Button>
+ * </CardFooter>
+ * ```
+ *
+ * @accessibility
+ * - Action buttons should have descriptive labels
+ * - Maintains logical tab order for interactive elements
+ * - Consider aria-label for icon-only buttons
+ *
+ * @param {string} [className] - Additional CSS classes to apply
+ * @param {React.HTMLAttributes<HTMLDivElement>} props - Standard HTML div attributes
+ * @since 1.0.0
+ */
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn("flex items-center px-6 [.border-t]:pt-6", className)}
+      {...props}
+    />
+  );
+}
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardAction,
+  CardDescription,
+  CardContent,
+};