@shoppexio/storefront-react 0.0.0 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 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,137 @@
+# @shoppexio/storefront-react
+
+The commerce layer and the customer account of a Shoppex code storefront
+(the Advanced lane). State, hooks, models and parsers from the package root;
+the account UI from `@shoppexio/storefront-react/account`. Decision record:
+ADR-0068.
+
+It reads two things the Shoppex worker puts on the page before your bundle
+runs: `window.shoppex` (the Storefront SDK, loaded as a CDN script by your
+`index.html`) and `window.__SHOPPEX_INITIAL__` (the shop, the catalog, the
+merchant's saved content). It never bundles the SDK.
+
+```sh
+bun add @shoppexio/storefront-react
+```
+
+Peer dependencies: `react` and `react-dom` 19.2, `react-router-dom` 7.18.
+
+## 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.
+
+## Mounting the account
+
+```tsx
+// src/pages/account-page.tsx, loaded with import() behind ACCOUNT_PATH
+import '@shoppexio/storefront-react/account.css';
+import { AccountPage as ShoppexAccount } from '@shoppexio/storefront-react/account';
+import { PageShell } from '../components/layout/page-shell';
+import { NotFoundPage } from './not-found-page';
+
+function Frame({ children }: { children: React.ReactNode }) {
+  return <PageShell page="account">{children}</PageShell>;
+}
+
+export function AccountPage() {
+  return <ShoppexAccount frame={Frame} notFound={<NotFoundPage />} />;
+}
+```
+
+- Mount it 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 locale is read from `<html lang>`, which the Shoppex worker sets. All
+  sixteen storefront locales ship with the account.
+
+## Styling the account
+
+The account has no look of its own. Every value in `account.css` is a read of
+one of your theme's `--sx-*` custom properties, so it takes your palette, type,
+radii and shadows, light and dark. Its utilities use the package-private `sxa:`
+prefix, so they cannot collide with your classes, and nothing in it selects
+your elements. It uses no cascade layer: a one-class `sxa:` rule beats your
+element resets (`button { color: inherit }`), and a rule of yours scoped under
+the root hook beats it.
+
+To restyle a part, target its hook under `.sx-account`. 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`.
+
+```css
+/* two classes beat the account's one-class utilities */
+.sx-account .sx-account-card { border-radius: 0; box-shadow: none; }
+.sx-account .sx-account-nav-link[aria-current='page'] { text-decoration: underline; }
+```
+
+`.sx-account` also scopes a zero-specificity baseline (box sizing, border
+reset, heading font) for themes without a CSS reset.
+
+### The CSS custom property contract
+
+A theme defines every one of these. A package test pins this list against the
+built stylesheet.
+
+<!-- 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.
+
+## Ejecting the account
+
+When restyling is not enough and you want to own the account's markup:
+
+1. Copy `node_modules/@shoppexio/storefront-react/eject/account/` into your
+   project as `src/account/`. Its imports of the package root 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
+   `sxa:` classes the copied markup carries. New markup uses your own classes.
+
+From then on the account is yours and a package update no longer reaches it.
+A CLI command for this is planned.
+
+## Versions
+
+Official templates pin an exact version. Monorepo maintainers move every pin
+at once with `bun run storefront-react:bump <version>` after publishing; see
+`docs/runbooks/theme-runtime-release.md`.