# 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.