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
+```