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