Initial Commit

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

@@ -0,0 +1,105 @@
+# 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.