# CartItem Component - Modern POS Cart Item Design

## Overview

A clean, modern cart item component designed specifically for the POS Sales Summary section. This component replaces the existing item layout with a streamlined, single-row design that maintains all functionality while providing an improved user experience.

## 🎨 Design Features

### Layout Structure

```
[Product Name]                    [-] 1 [+]                    EGP 450.00   ✕
EGP 450.00 each
```

### Key Design Elements

-   **Single-row layout** with clear sections
-   **Rounded corners** (`rounded-xl`) for modern appearance
-   **Subtle borders** (`border-gray-200`) with hover effects
-   **Light shadow** on hover for depth
-   **Smooth transitions** (`transition-all`, `duration-200`)
-   **White background** with balanced spacing (`p-4`)

## 📱 Component Structure

### Left Section - Product Info

-   **Product Name**: Bold, truncated if long (`font-bold`, `truncate`)
-   **Price per unit**: Smaller gray text (`text-gray-500`)
-   **Promotion Badge**: Optional badge for promotions/discounts

### Middle Section - Quantity Controls

-   **Minus Button**: Circular button with MinusIcon
-   **Quantity Display**: Current quantity in center
-   **Plus Button**: Circular button with PlusIcon
-   **Hover States**: Light gray tint on hover
-   **Focus States**: Blue ring for accessibility

### Right Section - Total & Delete

-   **Total Amount**: Bold, dark text (`font-bold`)
-   **Delete Button**: Small circular button with XMarkIcon
-   **Hover States**: Red tint on hover for delete action

## 🎯 Design Requirements Met

### ✅ Visual Layout

-   [x] Product name at top-left (bold, truncated if long)
-   [x] "EGP [price] each" below in smaller gray text
-   [x] Quantity controls horizontally in the middle
-   [x] Total amount and delete button on the far right

### ✅ Quantity Controls

-   [x] Circular button with MinusIcon on the left
-   [x] Current quantity displayed in the center
-   [x] Circular button with PlusIcon on the right

### ✅ Icons & Styling

-   [x] Heroicons outline set (MinusIcon, PlusIcon, XMarkIcon)
-   [x] Rounded corners (`rounded-xl`)
-   [x] Subtle borders (`border-gray-200`)
-   [x] Light shadow on hover
-   [x] Smooth transitions (`transition-all`, `duration-200`)
-   [x] White background with balanced spacing

### ✅ Responsive Design

-   [x] Proper alignment and spacing
-   [x] Text hierarchy maintained
-   [x] Responsive for smaller screens
-   [x] Consistent with other POS components

### ✅ Interactive States

-   [x] Hover states subtle but visible
-   [x] Active states for buttons
-   [x] Focus states for accessibility
-   [x] Disabled states for minimum quantity

## 🔧 Technical Implementation

### Props Interface

```typescript
interface CartItemProps {
    item: {
        product_id: number;
        category_id: number;
        name: string;
        qty: number;
        price: number;
        total: number;
        discount?: number;
        discount_type?: "value" | "percentage";
        is_free?: boolean;
        promotion_id?: number;
        promotion_name?: string;
        parent_item_id?: number;
        selection_strategy?: string;
        allocated_discount?: number;
    };
    onQuantityChange: (qty: number) => void;
    onRemove: (productId: number) => void;
    showPromotionBadges?: boolean;
    context?: "sale" | "return" | "exchange";
    showControls?: boolean;
}
```

### Key Features

-   **Data Logic Preservation**: Maintains all existing functionality
-   **Promotion Support**: Handles free items, discounts, and promotions
-   **Accessibility**: Proper ARIA labels and focus states
-   **Responsive**: Works across all screen sizes
-   **Consistent**: Aligns with existing POS UI patterns

## 🎨 Styling Details

### Color Scheme

-   **Background**: White with subtle borders
-   **Text**: Dark gray for primary text, lighter gray for secondary
-   **Buttons**: Gray borders with hover states
-   **Promotions**: Color-coded badges (green for free, blue for percentage, purple for fixed)
-   **Delete**: Red hover state for clear action indication

### Spacing & Layout

-   **Padding**: `p-4` for balanced internal spacing
-   **Gaps**: `gap-4` between major sections, `gap-2` for controls
-   **Margins**: `mb-1` for text hierarchy
-   **Min-width**: `min-w-[2rem]` for quantity display

### Interactive States

-   **Hover**: Light gray background (`hover:bg-gray-50`)
-   **Focus**: Blue ring (`focus:ring-2 focus:ring-blue-500`)
-   **Active**: Subtle scale or color changes
-   **Disabled**: Reduced opacity (`disabled:opacity-50`)

## 🚀 Usage Examples

### Basic Usage

```tsx
import CartItem from "@/components/POS/CartItem";

<CartItem
    item={{
        product_id: 1,
        category_id: 30,
        name: "TIE",
        qty: 1,
        price: 450,
        total: 450,
    }}
    onQuantityChange={(qty) => updateQuantity(qty)}
    onRemove={(productId) => removeItem(productId)}
    showControls={true}
    context="sale"
/>;
```

### With Promotions

```tsx
<CartItem
    item={{
        product_id: 1,
        category_id: 30,
        name: "TIE",
        qty: 1,
        price: 450,
        total: 0,
        is_free: true,
        promotion_id: 3,
        promotion_name: "Buy 2 Get 1 Free",
    }}
    onQuantityChange={(qty) => updateQuantity(qty)}
    onRemove={(productId) => removeItem(productId)}
    showPromotionBadges={true}
    context="sale"
/>
```

## 🔄 Migration from PosItem

### Key Differences

-   **Layout**: Single-row vs multi-row design
-   **Spacing**: More compact and organized
-   **Controls**: Circular buttons vs rectangular
-   **Typography**: Bold product names vs regular weight
-   **Interactions**: Enhanced hover and focus states

### Compatibility

-   **Props**: Same interface as PosItem
-   **Functionality**: Identical behavior
-   **Integration**: Drop-in replacement
-   **Styling**: Consistent with POS design system

## 🧪 Testing

### Visual Testing

-   [x] Desktop layout verification
-   [x] Mobile responsive design
-   [x] Hover state testing
-   [x] Focus state testing
-   [x] Promotion badge display

### Functional Testing

-   [x] Quantity increase/decrease
-   [x] Item removal
-   [x] Promotion handling
-   [x] Accessibility compliance
-   [x] Error state handling

## 📊 Benefits

### User Experience

-   **Cleaner Interface**: Single-row layout reduces visual clutter
-   **Better Hierarchy**: Clear information organization
-   **Improved Interactions**: Circular buttons feel more modern
-   **Enhanced Accessibility**: Proper focus states and ARIA labels

### Development

-   **Maintainable Code**: Clean, organized component structure
-   **Reusable Design**: Consistent with POS design system
-   **Type Safety**: Full TypeScript support
-   **Performance**: Optimized rendering and interactions

The CartItem component successfully modernizes the POS cart item display while maintaining all existing functionality and improving the overall user experience.