@shoppexio/storefront-react 0.0.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.1
+
+- README rewritten for theme developers: install, quick start, theming,
+  eject and links. Package metadata: support contact and keywords.
+
+## 0.1.0
+
+- First release. The commerce layer of the Shoppex code templates (SDK access,
+  payload parsing, storefront context, cart and quotes, catalog and product
+  models, checkout fields, reviews, shop pages, menus, contact, merchant HTML)
+  and the customer account (`@shoppexio/storefront-react/account`) with its
+  message catalogs for sixteen locales. The account is styled only through the
+  host theme's `--sx-*` custom properties and ships as plain CSS
+  (`@shoppexio/storefront-react/account.css`). See ADR-0068.
+- Physical products: `PHYSICAL` product type, `resolveDeliveryPromise()`
+  (`shipped` / `timed` / `instant`), `requiresShipping` on the cart context
+  from the quote's `requires_shipping`, and copy for the
+  `errors.checkout.shop_does_not_ship` refusal.
+- `formatMoney` drops zero cents on whole amounts (`$49`, `$49.50`); a
+  currency's own decimals are kept for every other amount.
+- Shop reviews carry `productTitle` and `verified`; `reviewsForProduct()`
+  narrows the feed to one product by title (the public feed has no product
+  ids, so the result is a sample, never a count).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoppex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# @shoppexio/storefront-react
+
+React hooks, models and a ready-made customer account for Shoppex code
+storefronts. A code storefront is a shop front you write yourself in React and
+Vite; Shoppex builds it, serves it on the shop's domain and runs checkout. This
+package handles the commerce part (catalog, product pages, cart, reviews, the
+signed-in customer area), so your code is the design.
+
+## Install
+
+```sh
+npm install @shoppexio/storefront-react
+bun add @shoppexio/storefront-react
+pnpm add @shoppexio/storefront-react
+```
+
+Peer dependencies: `react` and `react-dom` 19.2, `react-router-dom` 7.18.
+
+The package reads what Shoppex puts on the page before your bundle runs: the
+Storefront SDK as `window.shoppex` (a script tag in your `index.html`) and the
+shop's catalog and settings as `window.__SHOPPEX_INITIAL__`. It does not bundle
+the SDK, and it throws a clear error when either is missing.
+
+## Quick start
+
+```tsx
+// main.tsx
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter, Route, Routes } from 'react-router-dom';
+import {
+  ACCOUNT_PATH,
+  CartProvider,
+  formatMoney,
+  readStorefrontData,
+  StorefrontProvider,
+  useCart,
+  useStorefront,
+} from '@shoppexio/storefront-react';
+import { AccountPage } from '@shoppexio/storefront-react/account';
+import '@shoppexio/storefront-react/account.css';
+
+function Shelf() {
+  const { catalog } = useStorefront();
+  const { add, count, busy } = useCart();
+  return (
+    <main>
+      <p>{count} in cart</p>
+      {catalog.products.map((product) => (
+        <button
+          key={product.id}
+          disabled={busy}
+          onClick={() => add(product, product.priceVariants[0] ?? null, product.quantityMin)}
+        >
+          {product.name}, {formatMoney(product.price, product.currency)}
+        </button>
+      ))}
+    </main>
+  );
+}
+
+createRoot(document.getElementById('root')!).render(
+  <StorefrontProvider data={readStorefrontData()}>
+    <CartProvider>
+      <BrowserRouter>
+        <Routes>
+          <Route path="/" element={<Shelf />} />
+          <Route path={`${ACCOUNT_PATH}/*`} element={<AccountPage frame={({ children }) => <>{children}</>} notFound={<p>Not found</p>} />} />
+        </Routes>
+      </BrowserRouter>
+    </CartProvider>
+  </StorefrontProvider>,
+);
+```
+
+`useCart()` also gives you line updates, coupons, the live quote and
+`checkout()`, which sends the buyer to Shoppex checkout. Load the account with
+`import()` in a real theme so it stays out of your main bundle.
+
+## Features
+
+- Catalog: product and bundle cards, categories, sorting, filtering, paging.
+- Product pages: options, pricing per quantity, stock, badges, videos, the
+  rating breakdown.
+- Cart: add, update, remove, coupons, quotes from the server, checkout
+  hand-off, per-product checkout fields.
+- Reviews, shop pages, navigation menus and the contact form, from the SDK.
+- Merchant rich text, sanitized before you render it.
+- The customer account: sign-in, orders, downloads and keys, subscriptions,
+  rewards, referrals, reseller, support tickets and settings, in sixteen
+  languages.
+- Money formatting: `$49`, `$49.50`, `¥1,200`.
+
+## Theming the account
+
+The account has no look of its own. `account.css` reads your theme's `--sx-*`
+custom properties, so it takes your colours, type, radii and shadows in light
+and dark mode. Define the tokens once:
+
+```css
+:root {
+  --sx-bg: #0a0b0e;
+  --sx-surface: #111318;
+  --sx-accent: #3b5bf0;
+  --sx-on-accent: #ffffff;
+  --sx-radius-card: 16px;
+  /* the full list is below */
+}
+```
+
+To change one part, target its `sx-account-*` hook under `.sx-account`. Two
+classes beat the account's one-class utilities:
+
+```css
+.sx-account .sx-account-card { border-radius: 0; box-shadow: none; }
+.sx-account .sx-account-nav-link[aria-current='page'] { text-decoration: underline; }
+```
+
+The account's own classes carry an `sxa:` prefix, so they never collide with
+yours, and nothing in the stylesheet selects your elements.
+
+## Eject
+
+When tokens and hooks are not enough and you want to own the account's markup,
+copy it into your project:
+
+1. Copy `node_modules/@shoppexio/storefront-react/eject/account/` to
+   `src/account/`. Its imports already point at `@shoppexio/storefront-react`.
+2. Import `AccountPage` from `./account/account-page` instead of
+   `@shoppexio/storefront-react/account`.
+3. Keep importing `@shoppexio/storefront-react/account.css`; it styles the
+   classes the copied markup carries.
+
+From then on the account is yours, and package updates no longer change it.
+Most themes never need this.
+
+## Links
+
+- Docs: [Code storefront development](https://docs.shoppex.io/storefront/code-storefront-development),
+  [Customer accounts](https://docs.shoppex.io/storefront/code-storefront-accounts)
+- Example: the ForkMe template, a complete storefront built on this package.
+  Create a storefront from it in the Shoppex dashboard under
+  **Store → Storefronts**; see [Code storefronts](https://docs.shoppex.io/storefront/code-storefronts).
+- [Changelog](./CHANGELOG.md)
+- License: MIT
+
+## Reference
+
+### Entries
+
+| Import | What it is |
+|---|---|
+| `@shoppexio/storefront-react` | Logic, renders nothing (see the map below) |
+| `@shoppexio/storefront-react/account` | `AccountPage`, the whole customer account |
+| `@shoppexio/storefront-react/account.css` | The account's stylesheet, plain CSS |
+
+#### The root: where to start
+
+| Module | Use it for | Start with |
+|---|---|---|
+| SDK access | The SDK global, fail-fast when it is missing, affiliate capture | `getShoppex()`, `getBuyerCurrency()`, `SERVING_CONTEXT_HINT` |
+| Payload | Parsing the injected payload: products, groups, categories, shop, settings, stock, licence terms | `getProducts()`, `getStorefrontShop()`, `getStorefrontSettings()`, `hasInjectedStorefrontData()` |
+| Context | One parse at boot, read anywhere | `readStorefrontData()`, `<StorefrontProvider>`, `useStorefront()`, `useOnlineUserCount()` |
+| Catalog | Cards, sort, filter, pagination, money | `buildStorefrontCatalog()`, `sortCatalogCards()`, `filterCatalogCards()`, `formatMoney()` |
+| Product | The product page model: variants, rating, pricing, quantity bounds, badges, videos | `buildProductDetail()`, `calculateLinePricing()`, `badgesForProductPage()` |
+| Cart | Cart state, quotes, coupons, checkout hand-off | `<CartProvider>`, `useCart()`, `buildCartView()`, `buildCartTotals()` |
+| Checkout fields | Per-product fields a buyer fills before checkout | `resolveCheckoutFields()`, `readCheckoutNeedsDetails()` |
+| Reviews, pages, menus, contact | SDK-backed hooks | `useShopReviews()`, `loadShopPage()`, `useNavigationLinks()`, `submitContactTicket()` |
+| Merchant HTML | Sanitizing and flattening merchant rich text | `sanitizeMerchantHtml()`, `flattenMerchantHtmlToText()` |
+| Account routing | Mounting the account and its lazy chunk | `ACCOUNT_PATH`, `ACCOUNT_PATH_ALIAS`, `accountRouteMessage()`, `ACCOUNT_STOREFRONT_ROUTES`, `ACCOUNT_ARTIFACT_CAPABILITIES` |
+
+The `.d.ts` files next to the JS are the reference; every export carries its
+contract in its doc comment.
+
+### Account routing
+
+- Mount the account under `${ACCOUNT_PATH}/*` and `${ACCOUNT_PATH_ALIAS}/*`.
+- Route every path in `ACCOUNT_STOREFRONT_ROUTES`; the account links to them.
+- List every entry of `ACCOUNT_ARTIFACT_CAPABILITIES` in
+  `public/shoppex.capabilities.json`.
+- The account reads its language from `<html lang>`, which Shoppex sets.
+
+### Account hooks
+
+Hooks carry no styles:
+
+`sx-account` (root), `sx-account-header`, `sx-account-title`,
+`sx-account-signout`, `sx-account-nav`, `sx-account-nav-link`,
+`sx-account-panel` (with `data-sx-account-view="<tab>"`), `sx-account-card`,
+`sx-account-section-title`, `sx-account-empty`, `sx-account-error`,
+`sx-account-notice`, `sx-account-skeleton`, `sx-account-back`,
+`sx-account-button`, `sx-account-cta`, `sx-account-copy`, `sx-account-chip`,
+`sx-account-status`, `sx-account-field`, `sx-account-label`,
+`sx-account-field-error`.
+
+`.sx-account` also scopes a zero-specificity baseline (box sizing, border
+reset, heading font) for themes without a CSS reset. The stylesheet uses no
+cascade layer: a one-class `sxa:` rule beats your element resets, and a rule of
+yours scoped under `.sx-account` beats it.
+
+### CSS custom properties
+
+A theme defines every one of these.
+
+<!-- css-contract:start -->
+
+| Group | Properties |
+|---|---|
+| Colour | `--sx-bg`, `--sx-surface`, `--sx-surface-raised`, `--sx-heading`, `--sx-text`, `--sx-muted`, `--sx-line`, `--sx-accent`, `--sx-accent-hover`, `--sx-accent-line`, `--sx-on-accent`, `--sx-success`, `--sx-warning`, `--sx-error` |
+| Type | `--sx-font-heading`, `--sx-font-mono`, `--sx-text-h1`, `--sx-text-h2`, `--sx-text-h3`, `--sx-text-body`, `--sx-text-small`, `--sx-text-micro` |
+| Shape | `--sx-radius-card`, `--sx-radius-input`, `--sx-radius-badge`, `--sx-radius-button`, `--sx-border-w`, `--sx-shadow-card`, `--sx-shadow-button` |
+| Motion | `--sx-dur`, `--sx-ease` |
+
+<!-- css-contract:end -->
+
+Body text inherits the page's own font and colour.