Initial Commit

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

@@ -0,0 +1,90 @@
+# OpenSpec Change: enterprise-react-store
+
+- **Change ID**: enterprise-react-store
+- **Package**: `@suaveplan/react-store`
+- **Category**: react
+- **Target path**: `react/ui/react-store`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-store.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-store` on genesis from scratch at enterprise quality. White-label React storefront for multi-tenant e-commerce: `StoreClient` (products, cart, orders, wishlist, coupons), `StorefrontProvider`, hooks (`useStore`, `useProducts`), and ready-to-use component sets for Cart, Checkout, Orders, Product, Reviews, and Wishlist. Ships `formatMoney`, `StoreApiError`, and English translations. Genesis adds Storybook stories for every component, Playwright E2E for the full purchase flow, and 100% coverage.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `StoreApiError` base |
+| `@suaveplan/api-schemas` (`workspace:^`) | Shared pagination/sort schemas |
+| `@suaveplan/react-translate` (`workspace:^`) | i18n |
+| `@suaveplan/react-ui` (`workspace:^`) | UI primitives |
+| `zod` (`catalog:forms`) | Form schemas |
+
+External: `lucide-react catalog:ui`, `react-hook-form catalog:forms`, `tslib catalog:build`. React 18 peer.
+
+---
+
+## Preserved public API surface
+
+```ts
+// Client
+StoreClient, StoreApiError, formatMoney
+Address, Cart, CartItem, OrderConfirmation, ProductDetail,
+ProductListParams, ProductSummary, ProductVariant, StoreClientConfig
+
+// Context
+StorefrontProvider, useStore, useProducts
+
+// Components
+CartDrawer, CartItem (view), CartSummary
+AddressForm, CheckoutForm, OrderConfirmationView
+OrderHistory
+ProductCard, ProductDetail (view), ProductListing
+ReviewCard, ReviewForm, ReviewSection, StarRating
+WishlistButton, WishlistPage
+
+// i18n
+storeTranslationsEn, StoreTranslationKeys
+```
+
+---
+
+## New additions for genesis
+
+1. **Storybook for every component** — default, loading-state, error-state, playground.
+2. **Playwright E2E** — browse products → add to cart → checkout → order confirmation flow.
+3. **`StoreApiError`** extending `SuaveplanError` — codes: `STORE_FETCH_FAILED`, `STORE_CART_ERROR`, `STORE_CHECKOUT_FAILED`.
+4. **OTel instrumentation** — `store.add_to_cart`, `store.checkout` spans.
+
+---
+
+## File layout
+
+```text
+react/ui/react-store/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    client/ (store.client.ts + types + md + test + index)
+    context/ (store.context.tsx + md + test + index)
+    components/
+      cart/ product/ checkout/ orders/ review/ wishlist/
+    locales/
+      en.ts
+  e2e/
+    store-flow.spec.ts
+```

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.