cartly 1.0.2 → 1.0.4

package/README.md

@@ -1,5 +1,8 @@
 # cartly 🛒
 
+[![npm version](https://img.shields.io/npm/v/cartly.svg)](https://www.npmjs.com/package/cartly)
+[![license](https://img.shields.io/npm/l/cartly.svg)](https://github.com/sncorreia/cartly/blob/main/LICENSE)
+
 **cartly** is a lightweight, type-safe React Cart Context library built with modern hooks.  
 It’s designed to be **generic**, **framework-agnostic**, and easy to integrate into any React application — from e‑commerce stores to internal tools.
 
@@ -115,6 +118,25 @@ Call this once per app, export the result, and reuse it everywhere.
 
 💡 Pass storage={null} to disable persistence (recommended for SSR/tests).
 
+#### Custom Storage (SSR/Next.js)
+
+For SSR frameworks like Next.js, you can create a custom no-op storage adapter:
+
+```TypeScript
+import type { CartStorage } from "cartly";
+
+const noopStorage: CartStorage = {
+  getItem: () => null,
+  setItem: () => {},
+  removeItem: () => {},
+};
+
+// Usage
+<CartProvider storageKey="cart" storage={noopStorage}>
+  {children}
+</CartProvider>
+```
+
 ### useCart()
 
 ```TypeScript
@@ -128,6 +150,17 @@ const {
 } = useCart();
 ```
 
+#### Return Values
+
+| Return               | Type                                               | Description                              |
+| -------------------- | -------------------------------------------------- | ---------------------------------------- |
+| `cartItems`          | `CartItem<T>[]`                                    | Current cart items                       |
+| `addItemToCart`      | `(item: T) => void`                                | Add item (increments quantity if exists) |
+| `updateItemQuantity` | `(id: string \| number, quantity: number) => void` | Set item quantity                        |
+| `removeItemFromCart` | `(id: string \| number) => void`                   | Remove item from cart                    |
+| `clearCart`          | `() => void`                                       | Empty the cart                           |
+| `cartCount`          | `number`                                           | Total quantity of all items              |
+
 ### 🧾 Cart Item Shape
 
 ```TypeScript
@@ -159,6 +192,29 @@ cartly/
 
 MIT
 
+## ❓ FAQ
+
+### Why is my cart empty on page refresh?
+
+Make sure you're passing the correct `storageKey` and `storage` props to `CartProvider`. If `storage` is `null` or not provided, persistence is disabled.
+
+### How do I use this with Next.js or other SSR frameworks?
+
+Use `storage={null}` to disable persistence during SSR, or provide a custom storage adapter (see [Custom Storage](#custom-storage-ssrnextjs) section above).
+
+### Can I have multiple carts in the same app?
+
+Yes! Call `createCartContext<T>()` multiple times with different types and use separate providers:
+
+```TypeScript
+export const { CartProvider: ProductCartProvider, useCart: useProductCart } = createCartContext<Product>();
+export const { CartProvider: WishlistProvider, useCart: useWishlist } = createCartContext<WishlistItem>();
+```
+
+### Why does my item quantity not update?
+
+Ensure your item has a unique `id` property. The cart uses `id` to identify and update items.
+
 ## 🤝 Contributing
 
 Issues and PRs are welcome.

package/dist/src/CartProvider.d.ts

@@ -1,9 +1,26 @@
 import { CartContextType, CartStorage } from './types';
+/** Props for the CartProvider component */
 type Props = {
+    /** Child components that will have access to the cart context */
     children: React.ReactNode;
+    /** Key used for persisting cart data in storage (default: "cart") */
     storageKey?: string;
+    /** Storage mechanism for cart persistence (default: localStorage) */
     storage?: CartStorage;
 };
+/**
+ * Factory function that creates a typed cart context and its associated hooks/providers.
+ * This pattern allows for type-safe cart items with custom properties.
+ *
+ * @template T - The type of items in the cart, must have an `id` property
+ * @returns An object containing the CartProvider component and useCart hook
+ *
+ * @example
+ * ```tsx
+ * type Product = { id: string; name: string; price: number };
+ * const { CartProvider, useCart } = createCartContext<Product>();
+ * ```
+ */
 export declare function createCartContext<T extends {
     id: string | number;
 }>(): {

package/dist/src/index.d.ts

@@ -1,2 +1,7 @@
+/**
+ * Cartly - Generic, type-safe Cart Context & hooks for React
+ *
+ * @packageDocumentation
+ */
 export { createCartContext } from './CartProvider';
 export type { CartContextType, CartItem, CartStorage } from './types';

package/dist/src/types.d.ts

@@ -1,16 +1,31 @@
+/**
+ * Represents an item in the cart, extending the base item type with a quantity.
+ * @template T - The base item type, must have an `id` property
+ */
 export type CartItem<T extends {
     id: string | number;
 }> = T & {
+    /** Number of this item in the cart */
     quantity: number;
 };
+/**
+ * The shape of the cart context, providing state and operations for cart management.
+ * @template T - The base item type, must have an `id` property
+ */
 export type CartContextType<T extends {
     id: string | number;
 }> = {
+    /** Array of all items currently in the cart */
     cartItems: CartItem<T>[];
+    /** Adds an item to the cart or increments quantity if it already exists */
     addItemToCart: (item: T, quantity?: number) => void;
+    /** Updates the quantity of a specific item by its id */
     updateItemQuantity: (id: string | number, quantity: number) => void;
+    /** Removes an item completely from the cart by its id */
     removeItemFromCart: (id: string | number) => void;
+    /** Clears all items from the cart */
     clearCart: () => void;
+    /** Total count of all items in the cart (sum of quantities) */
     cartCount: number;
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cartly",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Generic, type-safe Cart Context & hooks for React",
   "main": "dist/index.cjs",
   "module": "dist/index.js",