Merge pull request #16 from deco-sites/jonasjesus/deco-5278-cart-com-optimistic-updates

feat(cart): optimistic updates for quantity change and item removal (DECO-5278)

Author: JonasJesus42

src/components/header/Bag.tsx

@@ -1,10 +1,17 @@
+import { useMutationState } from "@tanstack/react-query";
 import { MINICART_DRAWER_ID } from "../../constants";
 import Icon from "../ui/Icon";
 import { useCart } from "../../platform/cart";
 
 export default function Bag() {
   const { cart } = useCart();
   const count = cart.items.length;
+  // Global "cart busy" indicator: any in-flight cart mutation (add/update/
+  // remove) from anywhere in the tree, read via useMutationState by the
+  // ["cart", …] mutationKey — no prop drilling.
+  const busy = useMutationState({
+    filters: { mutationKey: ["cart"], status: "pending" },
+  }).length > 0;
   return (
     <label
       className="indicator"
@@ -17,7 +24,9 @@ export default function Bag() {
         </span>
       )}
       <span className="btn btn-square btn-sm btn-ghost no-animation">
-        <Icon id="shopping_bag" />
+        {busy
+          ? <span className="loading loading-spinner loading-xs" />
+          : <Icon id="shopping_bag" />}
       </span>
     </label>
   );

src/components/minicart/Minicart.tsx

@@ -13,16 +13,19 @@ import {
 
 function QuantityStepper({ item }: { item: CartItem }) {
   const update = useUpdateCartItem();
-  const pending = update.isPending && update.variables?.lineId === item.lineId;
   const set = (quantity: number) =>
     update.mutate({ lineId: item.lineId, quantity: Math.max(1, quantity) });
+  // No `pending` freeze: the quantity updates optimistically on click and the
+  // "cart" mutation scope serializes the requests, so rapid clicks stay
+  // consistent and the buttons remain interactive. Only the lower bound is
+  // disabled.
   return (
     <div className="join border border-base-200 rounded">
       <button
         type="button"
         className="join-item btn btn-ghost btn-sm no-animation"
         aria-label="Decrease quantity"
-        disabled={pending || item.quantity <= 1}
+        disabled={item.quantity <= 1}
         onClick={() => set(item.quantity - 1)}
       >
         -
@@ -34,7 +37,6 @@ function QuantityStepper({ item }: { item: CartItem }) {
         type="button"
         className="join-item btn btn-ghost btn-sm no-animation"
         aria-label="Increase quantity"
-        disabled={pending}
         onClick={() => set(item.quantity + 1)}
       >
         +

src/platform/cart/cart.hooks.ts

@@ -1,14 +1,54 @@
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { type QueryClient, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import {
   addItemServerFn,
   getCartServerFn,
   removeItemServerFn,
   updateItemQuantityServerFn,
 } from "./cart.actions";
-import { EMPTY_CART, type CartState } from "./cart.types";
+import { type CartItem, EMPTY_CART, type CartState } from "./cart.types";
 
 export const CART_QUERY_KEY = ["cart"] as const;
 
+interface OptimisticContext {
+  prev: CartState;
+}
+
+/**
+ * Applies new line items to a cart, re-deriving only the fields we can compute
+ * client-side: `subtotal` (Σ price × qty) and `totalQuantity`. `total` is left
+ * untouched on purpose — it may include discounts/shipping/tax we don't know
+ * here — and is reconciled from the server cart in `onSuccess`.
+ */
+function applyOptimisticItems(cart: CartState, items: CartItem[]): CartState {
+  return {
+    ...cart,
+    items,
+    totalQuantity: items.reduce((n, i) => n + i.quantity, 0),
+    subtotal: {
+      amount: items.reduce((sum, i) => sum + i.price.amount * i.quantity, 0),
+      currencyCode: cart.subtotal.currencyCode,
+    },
+  };
+}
+
+/**
+ * Shared optimistic-mutation plumbing: cancel in-flight cart fetches, snapshot
+ * the current cart for rollback, and write the transformed items to the cache.
+ */
+async function optimisticCartUpdate(
+  qc: QueryClient,
+  transform: (items: CartItem[]) => CartItem[],
+): Promise<OptimisticContext> {
+  await qc.cancelQueries({ queryKey: CART_QUERY_KEY });
+  const prev = qc.getQueryData<CartState>(CART_QUERY_KEY) ?? EMPTY_CART;
+  qc.setQueryData(CART_QUERY_KEY, applyOptimisticItems(prev, transform(prev.items)));
+  return { prev };
+}
+
+function rollbackCart(qc: QueryClient, ctx: OptimisticContext | undefined) {
+  if (ctx?.prev) qc.setQueryData(CART_QUERY_KEY, ctx.prev);
+}
+
 export function useCart() {
   const query = useQuery({
     queryKey: CART_QUERY_KEY,
@@ -27,8 +67,18 @@ export function useCart() {
 export function useAddToCart() {
   const qc = useQueryClient();
   return useMutation({
+    // Serialize all cart mutations (same scope id) so rapid actions run in
+    // order — the server sets absolute quantities, so out-of-order responses
+    // would otherwise clobber the cache. mutationKey lets useMutationState
+    // surface a global "cart busy" indicator.
+    scope: { id: "cart" },
+    mutationKey: ["cart", "add"],
     mutationFn: (input: { merchandiseId: string; quantity?: number }) =>
       addItemServerFn({ data: input }),
+    // NOTE(DECO-5278): optimistic add is deferred — building an optimistic
+    // line needs a product snapshot (title/image/price). It should come from a
+    // neutral `productToCartItem` mapping over commerce types, tracked as a
+    // remaining sub-item. Add already shows button feedback while in flight.
     onSuccess: (cart: CartState) => {
       qc.setQueryData(CART_QUERY_KEY, cart);
     },
@@ -38,8 +88,15 @@ export function useAddToCart() {
 export function useUpdateCartItem() {
   const qc = useQueryClient();
   return useMutation({
+    scope: { id: "cart" },
+    mutationKey: ["cart", "update"],
     mutationFn: (input: { lineId: string; quantity: number }) =>
       updateItemQuantityServerFn({ data: input }),
+    onMutate: ({ lineId, quantity }) =>
+      optimisticCartUpdate(qc, (items) =>
+        items.map((i) => (i.lineId === lineId ? { ...i, quantity: Math.max(1, quantity) } : i)),
+      ),
+    onError: (_err, _input, ctx) => rollbackCart(qc, ctx),
     onSuccess: (cart: CartState) => {
       qc.setQueryData(CART_QUERY_KEY, cart);
     },
@@ -49,8 +106,12 @@ export function useUpdateCartItem() {
 export function useRemoveCartItem() {
   const qc = useQueryClient();
   return useMutation({
-    mutationFn: (input: { lineId: string }) =>
-      removeItemServerFn({ data: input }),
+    scope: { id: "cart" },
+    mutationKey: ["cart", "remove"],
+    mutationFn: (input: { lineId: string }) => removeItemServerFn({ data: input }),
+    onMutate: ({ lineId }) =>
+      optimisticCartUpdate(qc, (items) => items.filter((i) => i.lineId !== lineId)),
+    onError: (_err, _input, ctx) => rollbackCart(qc, ctx),
     onSuccess: (cart: CartState) => {
       qc.setQueryData(CART_QUERY_KEY, cart);
     },