suaveplan/openspec/changes/enterprise-react-store/tasks.md

Tasks: enterprise-react-store

Change ID: enterprise-react-store Package: @suaveplan/react-store Target path: react/ui/react-store Prerequisite packages on Verdaccio: @suaveplan/error, @suaveplan/api-schemas, @suaveplan/react-translate, @suaveplan/react-ui

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree per proposal layout.
• Write package.json at 0.1.0 with "sideEffects": false, exports map.
• Dependencies: @suaveplan/error workspace:^, @suaveplan/api-schemas workspace:^, @suaveplan/react-translate workspace:^, @suaveplan/react-ui workspace:^, lucide-react catalog:ui, react-hook-form catalog:forms, zod catalog:forms, @opentelemetry/api catalog:observability, tslib catalog:build.
• Write tsconfig.json, vitest.config.ts, scripts.

---

2. StoreClient

• Define StoreApiError extending SuaveplanError; codes: STORE_FETCH_FAILED, STORE_CART_ERROR, STORE_CHECKOUT_FAILED.
• Implement StoreClient with injectable fetch: getProducts(params), getProduct(id), addToCart(item), removeFromCart(id), getCart(), clearCart(), createOrder(cart, address), getOrders(), addToWishlist(id), removeFromWishlist(id), getWishlist(), applyCoupon(code).
• Implement formatMoney(amount: number, currency: string): string using Intl.NumberFormat.
• Write store.client.test.ts (≤500 lines): each method, error wrapping, formatMoney. { timeout: 5000 }.
• Write store.client.md.

---

3. Context

• StorefrontProvider — accepts client: StoreClient; provides useStore and useProducts hooks.
• useStore — returns { cart, addToCart, removeFromCart, clearCart, createOrder, wishlist, addToWishlist, removeFromWishlist, applyCoupon }. OTel store.add_to_cart span.
• useProducts — returns { products, isLoading, error, fetchProducts(params) }.
• Write test + md.

---

4. Components

For each component group, implement all components with i18n + tests + stories (default, loading, error, playground) + md:

Cart

• CartDrawer — slide-in drawer showing CartSummary + items.
• CartItem (view) — image, name, quantity, price, remove button.
• CartSummary — subtotal, tax, total, checkout button.

Product

• ProductCard — image, name, price, add-to-cart, wishlist toggle.
• ProductListing — grid of ProductCard with useProducts.
• ProductDetail (view) — full product page with variants, gallery, add-to-cart.

Checkout

• AddressForm — react-hook-form + Zod schema for shipping address.
• CheckoutForm — multi-step: address + payment summary + confirm.
• OrderConfirmationView — success screen with order ID.

Orders

• OrderHistory — list of past orders with status badges.

Review

• StarRating — interactive or read-only star rating.
• ReviewCard — single review with author, rating, body.
• ReviewForm — react-hook-form + Zod.
• ReviewSection — list of ReviewCard + ReviewForm.

Wishlist

• WishlistButton — toggle heart icon.
• WishlistPage — full wishlist view.

---

5. Locales

• src/locales/en.ts — all user-visible strings as storeTranslationsEn; export StoreTranslationKeys type.

---

6. E2E

• e2e/store-flow.spec.ts — Playwright:
  • Open ProductListing, click ProductCard → ProductDetail shown.
  • Click "Add to cart" → CartDrawer opens, item visible.
  • Proceed through CheckoutForm → OrderConfirmationView shown.
  • Add product to wishlist → WishlistPage shows it.

---

7. Verify and publish

• bunx turbo lint typecheck test --filter=@suaveplan/react-store — green.
• bunx turbo test:coverage --filter=@suaveplan/react-store — 100%.
• bun scripts/publish.ts --package @suaveplan/react-store.
• Archive change folder.