react-shopping-cart-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Razan Aboushi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,429 @@
+# React Shopping Cart  🛒
+
+A modern, lightweight React shopping cart library with beautiful UI components. Perfect for e-commerce websites and marketplaces.
+
+## Features
+
+- **Multi-Currency Support** - Dynamic currency switching with real-time conversion
+- **Shipping Methods** - Configurable shipping options with costs
+- **Discount Codes** - Percentage or fixed amount discounts
+- **Internationalization** - English and Arabic with RTL support
+- **TypeScript** - Fully typed with generic product types
+- **Pre-built Components** - Beautiful, customizable UI components
+- **State Management** - Built with Zustand for optimal performance
+- **LocalStorage Persistence** - Cart saves automatically
+
+## Installation
+
+```bash
+npm install react-shopping-cart
+# or
+yarn add react-shopping-cart
+```
+
+### Requirements
+- React 18.0.0+
+- React DOM 18.0.0+
+- TypeScript 5.0+ (optional but recommended)
+
+## Quick Start
+
+### 1. Import Styles
+
+```tsx
+// main.tsx or App.tsx
+import 'react-shopping-cart/styles';
+```
+
+### 2. Wrap Your App with CartProvider
+
+```tsx
+import { CartProvider } from 'react-shopping-cart';
+
+const cartConfig = {
+  taxRate: 0.08,                    // 8% tax rate
+  currency: 'USD',                  // Default currency
+  availableCurrencies: [            // Multi-currency support
+    { code: 'USD', symbol: '$', name: 'US Dollar', conversionRate: 1.0 },
+    { code: 'EUR', symbol: '€', name: 'Euro', conversionRate: 0.92 },
+  ],
+  shippingMethods: [                // Shipping options
+    { id: 'standard', name: 'Standard Shipping', cost: 0, estimatedDays: '5-7 days' },
+    { id: 'express', name: 'Express Shipping', cost: 15, estimatedDays: '2-3 days' },
+  ],
+  discountCodes: [                  // Discount codes
+    { code: 'SAVE10', amount: 10, type: 'percentage' },
+  ],
+  showTax: true,
+  showDiscount: true,
+  showShipping: true,
+};
+
+function App() {
+  return (
+    <CartProvider config={cartConfig} language="en">
+      <YourApp />
+    </CartProvider>
+  );
+}
+```
+
+### 3. Use the Hook in Your Components
+
+```tsx
+import { useShoppingCart } from 'react-shopping-cart';
+
+function ProductCard({ product }) {
+  const { addItem, formatCurrency } = useShoppingCart();
+
+  return (
+    <div>
+      <h3>{product.name}</h3>
+      <p>{formatCurrency(product.price)}</p>
+      <button onClick={() => addItem(product)}>
+        Add to Cart
+      </button>
+    </div>
+  );
+}
+```
+
+### 4. Add Pre-built Components (Optional)
+
+```tsx
+import { CartButton, CartDrawer, CartSummary, CurrencySelector } from 'react-shopping-cart';
+
+function Header() {
+  return (
+    <header>
+      <CurrencySelector compact />
+      <CartButton showBadge badgePosition="top-right" />
+    </header>
+  );
+}
+
+function App() {
+  return (
+    <CartProvider config={cartConfig}>
+      <Header />
+      <CartDrawer position="right" />
+      <CartSummary showTax={true} showDiscount={true} />
+      <YourProductList />
+    </CartProvider>
+  );
+}
+```
+
+## Components
+
+### CartProvider
+
+Wraps your app to provide cart context.
+
+```tsx
+<CartProvider config={cartConfig} language="en">
+  <YourApp />
+</CartProvider>
+```
+
+**Props:**
+- `config` - Configuration object (see Configuration section)
+- `language` - Language code: `'en'` or `'ar'` (default: `'en'`)
+
+### CartButton
+
+Shopping cart icon with badge showing item count.
+
+```tsx
+<CartButton showBadge badgePosition="top-right" />
+```
+
+**Props:**
+- `showBadge` - Show item count badge (default: `true`)
+- `badgePosition` - `'top-right'` or `'top-left'` (default: `'top-right'`)
+- `className` - Additional CSS classes
+- `onClick` - Click handler
+
+### CartDrawer
+
+Side cart with smooth animation. Can be positioned as side drawer or centered popup.
+
+```tsx
+<CartDrawer position="right" showCheckoutButton onCheckout={() => {}} />
+```
+
+**Props:**
+- `position` - `'right'`, `'left'`, or `'center'` (default: `'right'`)
+- `showCheckoutButton` - Show checkout button (default: `true`)
+- `onCheckout` - Checkout handler function
+- `className` - Additional CSS classes
+
+### CartSummary
+
+Displays subtotal, discount, taxes, shipping, and total.
+
+```tsx
+<CartSummary showTax={true} showDiscount={true} showShipping={true} />
+```
+
+**Props:**
+- `showTax` - Show tax line (default: `true`)
+- `showDiscount` - Show discount line (default: `true`)
+- `showShipping` - Show shipping selection (default: `true`)
+
+### CurrencySelector
+
+Currency dropdown for switching between currencies.
+
+```tsx
+<CurrencySelector compact />
+```
+
+**Props:**
+- `compact` - Use compact dropdown style (default: `false`)
+- `showCurrencyName` - Show full currency name (default: `true`)
+
+### CartItems
+
+Renders all items in the cart.
+
+```tsx
+<CartItems emptyMessage="Your cart is empty" />
+```
+
+**Props:**
+- `emptyMessage` - Message when cart is empty (default: `'Your cart is empty'`)
+- `showRemoveButton` - Show remove button on items (default: `true`)
+
+### CartItem
+
+Individual cart item component.
+
+```tsx
+<CartItem item={product} showRemoveButton={true} />
+```
+
+**Props:**
+- `item` - Cart item data (required)
+- `showRemoveButton` - Show remove button (default: `true`)
+
+### CheckoutButton
+
+Primary checkout button with loading state.
+
+```tsx
+<CheckoutButton loading={false} onClick={() => {}}>
+  Checkout
+</CheckoutButton>
+```
+
+**Props:**
+- `loading` - Show loading state (default: `false`)
+- `disabled` - Disable button (default: `false`)
+- `onClick` - Click handler
+
+## useShoppingCart Hook
+
+The main hook for accessing cart state and actions.
+
+```tsx
+const {
+  // State
+  items,
+  subtotal,
+  tax,
+  shippingCost,
+  discountAmount,
+  total,
+  selectedCurrency,
+  
+  // Actions
+  addItem,
+  removeItem,
+  updateItemQuantity,
+  clearCart,
+  applyDiscount,
+  removeDiscount,
+  setSelectedShippingMethod,
+  setSelectedCurrency,
+  formatCurrency,
+} = useShoppingCart();
+```
+
+### State Properties
+
+- `items` - Array of cart items
+- `subtotal` - Subtotal in selected currency
+- `tax` - Tax amount in selected currency
+- `shippingCost` - Shipping cost in selected currency
+- `discountAmount` - Discount amount in selected currency
+- `total` - Total amount in selected currency
+- `selectedCurrency` - Currently selected currency code
+
+### Action Methods
+
+- `addItem(product)` - Add product to cart
+- `removeItem(id)` - Remove item from cart
+- `updateItemQuantity(id, quantity)` - Update item quantity
+- `clearCart()` - Clear all items from cart
+- `applyDiscount(code)` - Apply discount by code
+- `removeDiscount()` - Remove applied discount
+- `setSelectedShippingMethod(methodId)` - Select shipping method
+- `setSelectedCurrency(currencyCode)` - Switch currency
+- `formatCurrency(amount)` - Format amount with current currency
+
+## Configuration
+
+### CartConfig Object
+
+```typescript
+{
+  // Basic Settings
+  taxRate: 0.08,                    // Tax rate as decimal (0.08 = 8%)
+  currency: 'USD',                  // Default currency code
+  storageKey: 'react-shopping-cart', // localStorage key
+  persistToLocalStorage: true,      // Enable localStorage persistence
+  
+  // Currency Configuration
+  availableCurrencies: [...],       // Array of Currency objects
+  showCurrencySelector: true,       // Show currency selector
+  decimalPlaces: 2,                 // Number of decimal places
+  
+  // Shipping Configuration
+  shippingMethods: [...],           // Array of ShippingMethod objects
+  showShipping: true,               // Show shipping section
+  
+  // Discount Configuration
+  discountCodes: [...],             // Array of DiscountCode objects
+  showDiscount: true,               // Show discount input
+  
+  // Display Options
+  showTax: true,                    // Show tax line
+  theme: 'light',                  // 'light', 'dark', or 'auto'
+}
+```
+
+### Currency Object
+
+```typescript
+{
+  code: 'USD',                      // Currency code
+  symbol: '$',                      // Currency symbol
+  name: 'US Dollar',                // Display name
+  conversionRate: 1.0,              // Conversion rate from base currency
+}
+```
+
+### ShippingMethod Object
+
+```typescript
+{
+  id: 'standard',                   // Unique ID
+  name: 'Standard Shipping',       // Display name
+  description: '5-7 business days', // Description
+  cost: 0,                          // Cost in base currency
+  estimatedDays: '5-7 days',       // Estimated delivery
+  isDefault: false,                 // Is default option
+}
+```
+
+### DiscountCode Object
+
+```typescript
+{
+  code: 'SAVE10',                   // Discount code
+  amount: 10,                       // Discount amount
+  type: 'percentage',              // 'percentage' or 'fixed'
+  expiryDate?: '2024-12-31',       // Optional expiry date
+  usageLimit?: 100,                 // Optional usage limit
+}
+```
+
+## Multi-Currency Support
+
+All calculations (subtotal, tax, discount, shipping, total) are performed in the selected currency.
+
+**Example:**
+```tsx
+// Base: USD, User selects EUR (rate: 0.92)
+// $100 product → €92
+// Subtotal: €92 (converted)
+// Tax (8%): €7.36 (calculated on converted amount)
+// Total: €99.36 (all in EUR)
+```
+
+## Internationalization
+
+Built-in support for English and Arabic with automatic RTL layout for Arabic.
+
+**Set language:**
+```tsx
+<CartProvider config={cartConfig} language="ar">
+  <YourApp />
+</CartProvider>
+```
+
+**Available languages:**
+- `en` - English (default)
+- `ar` - Arabic (with RTL support)
+
+## TypeScript Support
+
+Fully typed with TypeScript. Extend the base product type for type safety:
+
+```tsx
+import { BaseProduct, useShoppingCart } from 'react-shopping-cart';
+
+interface MyProduct extends BaseProduct {
+  sku: string;
+  category: string;
+}
+
+function ProductPage() {
+  const { addItem, items } = useShoppingCart<MyProduct>();
+
+  const handleAdd = () => {
+    addItem({
+      id: '1',
+      name: 'Product',
+      price: 29.99,
+      sku: 'SKU-001',
+      category: 'Electronics',
+    });
+  };
+}
+```
+
+## Customization
+
+### CSS Variables
+
+Override CSS variables to customize the appearance:
+
+```css
+:root {
+  --rsc-primary-color: #3b82f6;
+  --rsc-primary-hover: #2563eb;
+  --rsc-accent-color: #10b981;
+  --rsc-danger-color: #ef4444;
+}
+```
+
+### Custom Styling
+
+```tsx
+<CartButton 
+  className="bg-purple-600 hover:bg-purple-700 text-white"
+  badgeClassName="bg-pink-500 text-white"
+/>
+```
+
+## License
+
+MIT © [Razan Aboushi](https://github.com/razan-aboushi)
+
+## Support
+
+- 📧 Email: razanalqaddoumi@gmail.com
+- 🐛 GitHub: https://github.com/razan-aboushi/react-shopping-cart
+- 💼 LinkedIn: https://www.linkedin.com/in/razan-aboushi/