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

// 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

Storybook for every component — default, loading-state, error-state, playground.
Playwright E2E — browse products → add to cart → checkout → order confirmation flow.
StoreApiError extending SuaveplanError — codes: STORE_FETCH_FAILED, STORE_CART_ERROR, STORE_CHECKOUT_FAILED.
OTel instrumentation — store.add_to_cart, store.checkout spans.

File layout

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

2.7 KiB Raw Blame History