cartly 1.0.2

package/README.md

@@ -0,0 +1,167 @@
+# cartly 🛒
+
+**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.
+
+- No external state libraries.
+- Strong TypeScript support.
+- Optional persistence.
+- Safe for SSR.
+
+## ✨ Features
+
+- ✅ Generic `createCartContext<T>()` API
+- ✅ `CartProvider` + `useCart` hook
+- ✅ Cart actions: add, update, remove, clear
+- ✅ Derived state (total item count)
+- ✅ Optional persistence (`localStorage`, `sessionStorage`, or disabled)
+- ✅ SSR-safe (no `window` access at import time)
+- ✅ Works with Material UI, Vite, Next.js, CRA
+- ✅ React as peer dependency (no duplicate React issues)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install cartly
+```
+
+## 📦 Peer Dependencies
+
+```bash
+npm install react react-dom
+```
+
+## 🚀 Quick Start
+
+### 1. Create a typed cart context (once per app)
+
+```Typescript
+import { createCartContext } from "cartly";
+
+export type Product = {
+  id: string;
+  name: string;
+  price: number;
+};
+
+export const { CartProvider, useCart } = createCartContext<Product>();
+```
+
+✅ This should be done once and re-exported.
+Do not call createCartContext in every component.
+
+### 2. Wrap your application
+
+```Typescript
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { CartProvider } from "./cart/cart";
+import App from "./App.tsx";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <CartProvider storageKey="cart" storage={localStorage}>
+      <App />
+    </CartProvider>
+  </StrictMode>,
+);
+```
+
+### 3. Use the cart anywhere
+
+```Typescript
+import { useCart } from "./cart/cart";
+
+export function AddToCartButton({ product }: { product: Product }) {
+  const { addItemToCart, cartCount } = useCart();
+
+  return (
+    <button onClick={() => addItemToCart(product)}>
+      Add to cart ({cartCount})
+    </button>
+  );
+}
+```
+
+## 🧠 API
+
+### createCartContext<T>()
+
+Creates a typed cart context for your application.
+
+```TypeScript
+const { CartProvider, useCart } = createCartContext<T>();
+```
+
+Call this once per app, export the result, and reuse it everywhere.
+
+### &lt;CartProvider&gt;
+
+```TypeScript
+<CartProvider  storageKey="cart"  storage={localStorage}>
+    {children}
+</CartProvider>
+```
+
+#### Props
+
+| Prop       | Type           | Required | Description                           |
+| ---------- | -------------- | -------- | ------------------------------------- |
+| children   | ReactNode      | ✅       | App tree                              |
+| storageKey | string         | ❌       | Storage key (default: "cart")         |
+| storage    | Storage / null | ❌       | localStorage, sessionStorage, or null |
+
+💡 Pass storage={null} to disable persistence (recommended for SSR/tests).
+
+### useCart()
+
+```TypeScript
+const {
+  cartItems,
+  addItemToCart,
+  updateItemQuantity,
+  removeItemFromCart,
+  clearCart,
+  cartCount
+} = useCart();
+```
+
+### 🧾 Cart Item Shape
+
+```TypeScript
+export type CartItem<T> = {
+  id: string | number;
+  item: T;
+  quantity: number;
+};
+```
+
+This avoids collisions if your product model already contains a quantity field.
+
+## 📁 Repository Structure
+
+```Plain Text
+cartly/
+├─ src/                # Library source
+├─ samples/            # Example apps
+│  └─ react-vite-demo/
+├─ dist/               # Build output (npm only)
+├─ package.json
+├─ vite.config.ts
+├─ tsconfig.json
+├─ README.md
+└─ LICENSE
+```
+
+## 📄 License
+
+MIT
+
+## 🤝 Contributing
+
+Issues and PRs are welcome.
+The library intentionally keeps a small, focused API surface.
+
+Built with React, TypeScript, and Vite.

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const y=require("react/jsx-runtime"),i=require("react");function w(u,s,d){try{const t=u.getItem(s);return t?JSON.parse(t):d}catch(t){return console.log(t),u.removeItem(s),d}}function O(){const u=i.createContext(void 0);function s({children:t,storageKey:m="cart",storage:f=localStorage}){const[a,C]=i.useState(()=>w(f,m,[]));i.useEffect(()=>{f.setItem(m,JSON.stringify(a))},[a,f,m]);const x=(e,r=1)=>{C(n=>n.find(c=>c.id==e.id)?n.map(c=>c.id==e.id?{...c,quantity:c.quantity+r}:c):[...n,{...e,quantity:r}])},l=(e,r)=>{C(n=>n.map(o=>o.id==e?{...o,quantity:r}:o).filter(o=>o.quantity>0))},I=e=>{C(r=>r.filter(n=>n.id!==e))},S=()=>{C([])},v=i.useMemo(()=>a.reduce((e,r)=>e+r.quantity,0),[a]),q={cartItems:a,addItemToCart:x,updateItemQuantity:l,removeItemFromCart:I,clearCart:S,cartCount:v};return y.jsx(u.Provider,{value:q,children:t})}function d(){const t=i.useContext(u);if(!t)throw new Error("useCart must be used within a CartProvider.");return t}return{CartProvider:s,useCart:d}}exports.createCartContext=O;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './src/index'
+export {}

package/dist/index.js

@@ -0,0 +1,59 @@
+import { jsx as S } from "react/jsx-runtime";
+import { createContext as w, useContext as h, useState as q, useEffect as y, useMemo as J } from "react";
+function N(c, i, s) {
+  try {
+    const t = c.getItem(i);
+    return t ? JSON.parse(t) : s;
+  } catch (t) {
+    return console.log(t), c.removeItem(i), s;
+  }
+}
+function E() {
+  const c = w(void 0);
+  function i({
+    children: t,
+    storageKey: m = "cart",
+    storage: C = localStorage
+  }) {
+    const [u, d] = q(
+      () => N(C, m, [])
+    );
+    y(() => {
+      C.setItem(m, JSON.stringify(u));
+    }, [u, C, m]);
+    const f = (r, e = 1) => {
+      d((n) => n.find((a) => a.id == r.id) ? n.map(
+        (a) => a.id == r.id ? { ...a, quantity: a.quantity + e } : a
+      ) : [...n, { ...r, quantity: e }]);
+    }, x = (r, e) => {
+      d(
+        (n) => n.map((o) => o.id == r ? { ...o, quantity: e } : o).filter((o) => o.quantity > 0)
+      );
+    }, I = (r) => {
+      d((e) => e.filter((n) => n.id !== r));
+    }, l = () => {
+      d([]);
+    }, p = J(
+      () => u.reduce((r, e) => r + e.quantity, 0),
+      [u]
+    ), v = {
+      cartItems: u,
+      addItemToCart: f,
+      updateItemQuantity: x,
+      removeItemFromCart: I,
+      clearCart: l,
+      cartCount: p
+    };
+    return /* @__PURE__ */ S(c.Provider, { value: v, children: t });
+  }
+  function s() {
+    const t = h(c);
+    if (!t)
+      throw new Error("useCart must be used within a CartProvider.");
+    return t;
+  }
+  return { CartProvider: i, useCart: s };
+}
+export {
+  E as createCartContext
+};

package/dist/src/CartProvider.d.ts

@@ -0,0 +1,13 @@
+import { CartContextType, CartStorage } from './types';
+type Props = {
+    children: React.ReactNode;
+    storageKey?: string;
+    storage?: CartStorage;
+};
+export declare function createCartContext<T extends {
+    id: string | number;
+}>(): {
+    CartProvider: ({ children, storageKey, storage, }: Props) => import("react/jsx-runtime").JSX.Element;
+    useCart: () => CartContextType<T>;
+};
+export {};

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { createCartContext } from './CartProvider';
+export type { CartContextType, CartItem, CartStorage } from './types';

package/dist/src/storage.d.ts

@@ -0,0 +1,13 @@
+import { CartStorage } from './types';
+/**
+ * Safely read JSON from storage, returning a fallback value if parsing fails or if the item does not exist
+ *
+ * @remarks
+ * This function attempts to read a JSON string from the provided storage using the specified key.
+ *
+ * @param storage - The storage object to read from.
+ * @param key - The key to read the JSON string from.
+ * @param fallback - The fallback value to return if parsing fails or the item does not exist.
+ * @returns The parsed JSON value or the fallback value.
+ */
+export declare function safeReadJSON<T>(storage: CartStorage, key: string, fallback: T): T;

package/dist/src/types.d.ts

@@ -0,0 +1,22 @@
+export type CartItem<T extends {
+    id: string | number;
+}> = T & {
+    quantity: number;
+};
+export type CartContextType<T extends {
+    id: string | number;
+}> = {
+    cartItems: CartItem<T>[];
+    addItemToCart: (item: T, quantity?: number) => void;
+    updateItemQuantity: (id: string | number, quantity: number) => void;
+    removeItemFromCart: (id: string | number) => void;
+    clearCart: () => void;
+    cartCount: number;
+};
+/**
+ * A simplified interface for storage objects, focusing on essential methods for cart management.
+ *
+ * @remarks
+ * This type includes only the `getItem`, `setItem`, and `removeItem` methods from the standard Storage interface.
+ */
+export type CartStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;

package/dist/vite.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import('vite').UserConfig;
+export default _default;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "cartly",
+  "version": "1.0.2",
+  "description": "Generic, type-safe Cart Context & hooks for React",
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run build"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react-swc": "^4.2.2",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1",
+    "vite-plugin-dts": "^4.5.4"
+  }
+}