@optilogic/core 1.0.0-beta.1 → 1.0.0-beta.10

package/src/components/card.tsx

@@ -1,28 +1,173 @@
 import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
 
 import { cn } from "../utils/cn";
+import { Checkbox } from "./checkbox";
 
-export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {}
+// =============================================================================
+// Card Variants
+// =============================================================================
 
 /**
- * Card - Container component for grouped content
+ * Card variant styles using class-variance-authority.
+ * Provides size, hover effects, and interactive styling options.
+ */
+const cardVariants = cva(
+  "rounded-xl border bg-card text-card-foreground shadow",
+  {
+    variants: {
+      /**
+       * Card width size presets
+       */
+      size: {
+        auto: "",
+        sm: "w-64",
+        md: "w-80",
+        lg: "w-96",
+        xl: "w-[28rem]",
+        full: "w-full",
+      },
+      /**
+       * Hover effect styles
+       */
+      hover: {
+        none: "",
+        lift: "transition-all duration-200 hover:-translate-y-1 hover:shadow-lg",
+        glow: "transition-shadow duration-200 hover:shadow-lg hover:shadow-accent/20",
+        border: "transition-colors duration-200 hover:border-accent",
+        "border-success": "transition-colors duration-200 hover:border-success",
+        "border-warning": "transition-colors duration-200 hover:border-warning",
+        "border-destructive": "transition-colors duration-200 hover:border-destructive",
+        "border-muted": "transition-colors duration-200 hover:border-muted-foreground",
+        scale: "transition-transform duration-200 hover:scale-[1.02]",
+      },
+      /**
+       * Whether the card is interactive (clickable)
+       */
+      interactive: {
+        true: "cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+        false: "",
+      },
+      /**
+       * Card padding density
+       */
+      padding: {
+        none: "",
+        sm: "[&>*:not(img)]:p-3 [&>*:not(img)]:pt-3",
+        md: "",
+        lg: "[&>*:not(img)]:p-8 [&>*:not(img)]:pt-8",
+      },
+    },
+    defaultVariants: {
+      size: "auto",
+      hover: "none",
+      interactive: false,
+      padding: "md",
+    },
+  }
+);
+
+// =============================================================================
+// Base Card Component
+// =============================================================================
+
+export interface CardProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof cardVariants> {
+  /**
+   * If true, the card acts as a button and can be clicked.
+   * Adds keyboard accessibility and focus states.
+   */
+  asButton?: boolean;
+  /**
+   * Custom CSS class for hover border color.
+   * Use Tailwind classes like "hover:border-blue-500" or custom CSS variables.
+   * This overrides the hover variant's border color if specified.
+   */
+  hoverBorderClass?: string;
+}
+
+/**
+ * Card - Versatile container component for grouped content
+ *
+ * A flexible card component supporting multiple sizes, hover effects,
+ * and interactive states. Use with CardHeader, CardContent, CardFooter,
+ * and other sub-components.
+ *
+ * @example
+ * <Card size="md" hover="lift">
+ *   <CardHeader>
+ *     <CardTitle>Title</CardTitle>
+ *   </CardHeader>
+ *   <CardContent>Content here</CardContent>
+ * </Card>
+ *
+ * @example
+ * <Card interactive hover="border" onClick={() => navigate('/item')}>
+ *   <CardContent>Clickable card</CardContent>
+ * </Card>
  */
 const Card = React.forwardRef<HTMLDivElement, CardProps>(
-  ({ className, ...props }, ref) => (
-    <div
-      ref={ref}
-      className={cn(
-        "rounded-xl border bg-card text-card-foreground shadow",
-        className
-      )}
-      {...props}
-    />
-  )
+  (
+    {
+      className,
+      size,
+      hover,
+      interactive,
+      padding,
+      asButton,
+      hoverBorderClass,
+      onClick,
+      onKeyDown,
+      ...props
+    },
+    ref
+  ) => {
+    // If asButton is true, make the card interactive
+    const isInteractive = interactive || asButton || !!onClick;
+
+    const handleKeyDown = React.useCallback(
+      (e: React.KeyboardEvent<HTMLDivElement>) => {
+        if (isInteractive && (e.key === "Enter" || e.key === " ")) {
+          e.preventDefault();
+          onClick?.(e as unknown as React.MouseEvent<HTMLDivElement>);
+        }
+        onKeyDown?.(e);
+      },
+      [isInteractive, onClick, onKeyDown]
+    );
+
+    return (
+      <div
+        ref={ref}
+        role={isInteractive ? "button" : undefined}
+        tabIndex={isInteractive ? 0 : undefined}
+        className={cn(
+          cardVariants({ size, hover, interactive: isInteractive, padding }),
+          "group relative",
+          // Custom hover border color overrides variant if provided
+          hoverBorderClass && "transition-colors duration-200",
+          hoverBorderClass,
+          className
+        )}
+        onClick={onClick}
+        onKeyDown={handleKeyDown}
+        {...props}
+      />
+    );
+  }
 );
 Card.displayName = "Card";
 
+// =============================================================================
+// Card Sub-Components
+// =============================================================================
+
 export interface CardHeaderProps extends React.HTMLAttributes<HTMLDivElement> {}
 
+/**
+ * CardHeader - Header section of a card
+ */
 const CardHeader = React.forwardRef<HTMLDivElement, CardHeaderProps>(
   ({ className, ...props }, ref) => (
     <div
@@ -36,6 +181,9 @@ CardHeader.displayName = "CardHeader";
 
 export interface CardTitleProps extends React.HTMLAttributes<HTMLDivElement> {}
 
+/**
+ * CardTitle - Title text for card header
+ */
 const CardTitle = React.forwardRef<HTMLDivElement, CardTitleProps>(
   ({ className, ...props }, ref) => (
     <div
@@ -50,6 +198,9 @@ CardTitle.displayName = "CardTitle";
 export interface CardDescriptionProps
   extends React.HTMLAttributes<HTMLDivElement> {}
 
+/**
+ * CardDescription - Descriptive text for card header
+ */
 const CardDescription = React.forwardRef<HTMLDivElement, CardDescriptionProps>(
   ({ className, ...props }, ref) => (
     <div
@@ -64,6 +215,9 @@ CardDescription.displayName = "CardDescription";
 export interface CardContentProps
   extends React.HTMLAttributes<HTMLDivElement> {}
 
+/**
+ * CardContent - Main content area of a card
+ */
 const CardContent = React.forwardRef<HTMLDivElement, CardContentProps>(
   ({ className, ...props }, ref) => (
     <div ref={ref} className={cn("p-6 pt-0", className)} {...props} />
@@ -73,6 +227,9 @@ CardContent.displayName = "CardContent";
 
 export interface CardFooterProps extends React.HTMLAttributes<HTMLDivElement> {}
 
+/**
+ * CardFooter - Footer section of a card
+ */
 const CardFooter = React.forwardRef<HTMLDivElement, CardFooterProps>(
   ({ className, ...props }, ref) => (
     <div
@@ -84,11 +241,498 @@ const CardFooter = React.forwardRef<HTMLDivElement, CardFooterProps>(
 );
 CardFooter.displayName = "CardFooter";
 
+// =============================================================================
+// CardImage Component
+// =============================================================================
+
+const cardImageVariants = cva("w-full object-cover", {
+  variants: {
+    /**
+     * Image aspect ratio
+     */
+    aspectRatio: {
+      auto: "",
+      square: "aspect-square",
+      video: "aspect-video",
+      wide: "aspect-[2/1]",
+      portrait: "aspect-[3/4]",
+    },
+    /**
+     * Image position in the card
+     */
+    position: {
+      top: "rounded-t-xl",
+      bottom: "rounded-b-xl",
+      fill: "rounded-xl",
+    },
+  },
+  defaultVariants: {
+    aspectRatio: "video",
+    position: "top",
+  },
+});
+
+export interface CardImageProps
+  extends React.ImgHTMLAttributes<HTMLImageElement>,
+    VariantProps<typeof cardImageVariants> {
+  /**
+   * Fallback content to display if image fails to load
+   */
+  fallback?: React.ReactNode;
+}
+
+/**
+ * CardImage - Image/media component for cards
+ *
+ * Displays images with configurable aspect ratios and positions.
+ * Handles loading states and fallbacks.
+ *
+ * @example
+ * <Card>
+ *   <CardImage src="/photo.jpg" alt="Photo" aspectRatio="video" />
+ *   <CardContent>Caption</CardContent>
+ * </Card>
+ */
+const CardImage = React.forwardRef<HTMLImageElement, CardImageProps>(
+  (
+    { className, aspectRatio, position, fallback, alt, src, onError, ...props },
+    ref
+  ) => {
+    const [hasError, setHasError] = React.useState(false);
+
+    const handleError = React.useCallback(
+      (e: React.SyntheticEvent<HTMLImageElement>) => {
+        setHasError(true);
+        onError?.(e);
+      },
+      [onError]
+    );
+
+    // Reset error state when src changes
+    React.useEffect(() => {
+      setHasError(false);
+    }, [src]);
+
+    if (hasError && fallback) {
+      return (
+        <div
+          className={cn(
+            "flex items-center justify-center bg-muted",
+            cardImageVariants({ aspectRatio, position }),
+            className
+          )}
+        >
+          {fallback}
+        </div>
+      );
+    }
+
+    return (
+      <img
+        ref={ref}
+        src={src}
+        alt={alt}
+        className={cn(cardImageVariants({ aspectRatio, position }), className)}
+        onError={handleError}
+        {...props}
+      />
+    );
+  }
+);
+CardImage.displayName = "CardImage";
+
+// =============================================================================
+// CardActions Component
+// =============================================================================
+
+const cardActionsVariants = cva(
+  "absolute flex items-center gap-1 transition-opacity duration-200 z-10",
+  {
+    variants: {
+      /**
+       * When to show the actions
+       */
+      showOn: {
+        hover: "opacity-0 group-hover:opacity-100",
+        always: "opacity-100",
+      },
+      /**
+       * Position of the actions overlay
+       */
+      position: {
+        "top-right": "top-2 right-2",
+        "top-left": "top-2 left-2",
+        "bottom-right": "bottom-2 right-2",
+        "bottom-left": "bottom-2 left-2",
+      },
+      /**
+       * Visual style of the actions container
+       */
+      variant: {
+        /** Solid background with backdrop blur */
+        floating: "bg-background/90 backdrop-blur-sm rounded-md shadow-sm p-1",
+        /** No background, just spacing */
+        ghost: "p-1",
+        /** Muted bar background */
+        bar: "bg-muted/80 backdrop-blur-sm rounded-md p-1.5",
+        /** No background on container, icons get background on hover */
+        "icon-hover":
+          "p-0 [&>button]:bg-transparent [&>button]:hover:bg-background/90 [&>button]:hover:shadow-sm [&>button]:transition-all",
+      },
+    },
+    defaultVariants: {
+      showOn: "hover",
+      position: "top-right",
+      variant: "floating",
+    },
+  }
+);
+
+export interface CardActionsProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof cardActionsVariants> {}
+
+/**
+ * CardActions - Hover-reveal action buttons for cards
+ *
+ * Place action buttons that appear on hover. Position can be customized.
+ * The parent Card automatically gets the 'group' class for hover detection.
+ *
+ * @example
+ * <Card hover="lift">
+ *   <CardActions>
+ *     <IconButton size="sm" variant="ghost"><Edit /></IconButton>
+ *     <IconButton size="sm" variant="ghost"><Trash /></IconButton>
+ *   </CardActions>
+ *   <CardContent>Content</CardContent>
+ * </Card>
+ *
+ * @example
+ * // With floating style (default)
+ * <CardActions variant="floating">...</CardActions>
+ *
+ * @example
+ * // With bar style for image overlays
+ * <CardActions variant="bar" position="bottom-right">...</CardActions>
+ */
+const CardActions = React.forwardRef<HTMLDivElement, CardActionsProps>(
+  ({ className, showOn, position, variant, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(cardActionsVariants({ showOn, position, variant }), className)}
+      // Prevent clicks from bubbling to parent card
+      onClick={(e) => e.stopPropagation()}
+      {...props}
+    />
+  )
+);
+CardActions.displayName = "CardActions";
+
+// =============================================================================
+// SelectableCard Component
+// =============================================================================
+
+export interface SelectableCardProps extends CardProps {
+  /**
+   * Whether the card is selected (controlled)
+   */
+  selected?: boolean;
+  /**
+   * Default selected state (uncontrolled)
+   */
+  defaultSelected?: boolean;
+  /**
+   * Callback when selection changes
+   */
+  onSelectedChange?: (selected: boolean) => void;
+  /**
+   * Whether to show a visible checkbox
+   */
+  showCheckbox?: boolean;
+  /**
+   * Position of the checkbox
+   */
+  checkboxPosition?: "top-left" | "top-right" | "inline-left";
+  /**
+   * Whether the card is disabled
+   */
+  disabled?: boolean;
+}
+
+/**
+ * SelectableCard - Card with selection state
+ *
+ * A card that can be selected/deselected. Supports controlled and uncontrolled modes.
+ * Can optionally display a checkbox indicator.
+ *
+ * @example
+ * <SelectableCard
+ *   selected={isSelected}
+ *   onSelectedChange={setIsSelected}
+ *   showCheckbox
+ * >
+ *   <CardContent>Selectable content</CardContent>
+ * </SelectableCard>
+ *
+ * @example
+ * // Multi-select list with inline checkbox
+ * {items.map(item => (
+ *   <SelectableCard
+ *     key={item.id}
+ *     selected={selectedIds.includes(item.id)}
+ *     onSelectedChange={(sel) => toggleSelection(item.id, sel)}
+ *     showCheckbox
+ *     checkboxPosition="inline-left"
+ *   >
+ *     <CardContent>{item.name}</CardContent>
+ *   </SelectableCard>
+ * ))}
+ */
+const SelectableCard = React.forwardRef<HTMLDivElement, SelectableCardProps>(
+  (
+    {
+      className,
+      selected: controlledSelected,
+      defaultSelected = false,
+      onSelectedChange,
+      showCheckbox = false,
+      checkboxPosition = "top-right",
+      disabled = false,
+      children,
+      onClick,
+      hover = "border",
+      ...props
+    },
+    ref
+  ) => {
+    // Support both controlled and uncontrolled modes
+    const [uncontrolledSelected, setUncontrolledSelected] =
+      React.useState(defaultSelected);
+    const isControlled = controlledSelected !== undefined;
+    const isSelected = isControlled ? controlledSelected : uncontrolledSelected;
+
+    const handleClick = React.useCallback(
+      (e: React.MouseEvent<HTMLDivElement>) => {
+        if (disabled) return;
+
+        const newSelected = !isSelected;
+        if (!isControlled) {
+          setUncontrolledSelected(newSelected);
+        }
+        onSelectedChange?.(newSelected);
+        onClick?.(e);
+      },
+      [disabled, isSelected, isControlled, onSelectedChange, onClick]
+    );
+
+    const handleCheckboxChange = React.useCallback(
+      (checked: boolean | "indeterminate") => {
+        if (disabled) return;
+
+        const newSelected = checked === true;
+        if (!isControlled) {
+          setUncontrolledSelected(newSelected);
+        }
+        onSelectedChange?.(newSelected);
+      },
+      [disabled, isControlled, onSelectedChange]
+    );
+
+    // Inline checkbox renders in a dedicated control bar
+    const isInline = checkboxPosition === "inline-left";
+
+    return (
+      <Card
+        ref={ref}
+        className={cn(
+          // Selection styling
+          isSelected && "ring-2 ring-accent border-accent",
+          disabled && "opacity-50 cursor-not-allowed",
+          className
+        )}
+        interactive={!disabled}
+        hover={disabled ? "none" : hover}
+        onClick={handleClick}
+        aria-selected={isSelected}
+        aria-disabled={disabled}
+        {...props}
+      >
+        {showCheckbox && isInline && (
+          <div
+            className="flex items-center gap-3 px-4 py-3 border-b border-border/50"
+            onClick={(e) => e.stopPropagation()}
+          >
+            <Checkbox
+              checked={isSelected}
+              onCheckedChange={handleCheckboxChange}
+              disabled={disabled}
+            />
+            <span className="text-xs text-muted-foreground">
+              {isSelected ? "Selected" : "Click to select"}
+            </span>
+          </div>
+        )}
+        {showCheckbox && !isInline && (
+          <div
+            className={cn(
+              "absolute z-10 p-1 bg-background/90 backdrop-blur-sm rounded-md",
+              checkboxPosition === "top-left" ? "top-2 left-2" : "top-2 right-2"
+            )}
+            onClick={(e) => e.stopPropagation()}
+          >
+            <Checkbox
+              checked={isSelected}
+              onCheckedChange={handleCheckboxChange}
+              disabled={disabled}
+            />
+          </div>
+        )}
+        {children}
+      </Card>
+    );
+  }
+);
+SelectableCard.displayName = "SelectableCard";
+
+// =============================================================================
+// Layout Components
+// =============================================================================
+
+const cardGridVariants = cva("grid", {
+  variants: {
+    /**
+     * Number of columns
+     */
+    columns: {
+      1: "grid-cols-1",
+      2: "grid-cols-1 sm:grid-cols-2",
+      3: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3",
+      4: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4",
+      auto: "grid-cols-[repeat(auto-fill,minmax(280px,1fr))]",
+    },
+    /**
+     * Gap between cards
+     */
+    gap: {
+      none: "gap-0",
+      sm: "gap-3",
+      md: "gap-4",
+      lg: "gap-6",
+      xl: "gap-8",
+    },
+  },
+  defaultVariants: {
+    columns: "auto",
+    gap: "md",
+  },
+});
+
+export interface CardGridProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof cardGridVariants> {}
+
+/**
+ * CardGrid - Responsive grid layout for cards
+ *
+ * Arranges cards in a responsive grid with configurable columns and gaps.
+ *
+ * @example
+ * <CardGrid columns={3} gap="lg">
+ *   <Card>...</Card>
+ *   <Card>...</Card>
+ *   <Card>...</Card>
+ * </CardGrid>
+ *
+ * @example
+ * // Auto-fill columns based on available space
+ * <CardGrid columns="auto">
+ *   {items.map(item => <Card key={item.id}>...</Card>)}
+ * </CardGrid>
+ */
+const CardGrid = React.forwardRef<HTMLDivElement, CardGridProps>(
+  ({ className, columns, gap, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(cardGridVariants({ columns, gap }), className)}
+      {...props}
+    />
+  )
+);
+CardGrid.displayName = "CardGrid";
+
+const cardListVariants = cva("flex flex-col", {
+  variants: {
+    /**
+     * Gap between cards
+     */
+    gap: {
+      none: "gap-0",
+      sm: "gap-2",
+      md: "gap-4",
+      lg: "gap-6",
+    },
+    /**
+     * Whether to show dividers between cards
+     */
+    divided: {
+      true: "[&>*:not(:last-child)]:border-b [&>*:not(:last-child)]:pb-4 [&>*:not(:last-child)]:rounded-b-none",
+      false: "",
+    },
+  },
+  defaultVariants: {
+    gap: "md",
+    divided: false,
+  },
+});
+
+export interface CardListProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof cardListVariants> {}
+
+/**
+ * CardList - Vertical list layout for cards
+ *
+ * Arranges cards in a vertical list with optional dividers.
+ *
+ * @example
+ * <CardList gap="sm" divided>
+ *   <Card>...</Card>
+ *   <Card>...</Card>
+ * </CardList>
+ */
+const CardList = React.forwardRef<HTMLDivElement, CardListProps>(
+  ({ className, gap, divided, ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn(cardListVariants({ gap, divided }), className)}
+      {...props}
+    />
+  )
+);
+CardList.displayName = "CardList";
+
+// =============================================================================
+// Exports
+// =============================================================================
+
 export {
+  // Core components
   Card,
   CardHeader,
   CardFooter,
   CardTitle,
   CardDescription,
   CardContent,
+  // New components
+  CardImage,
+  CardActions,
+  SelectableCard,
+  CardGrid,
+  CardList,
+  // Variants (for advanced customization)
+  cardVariants,
+  cardImageVariants,
+  cardActionsVariants,
+  cardGridVariants,
+  cardListVariants,
 };