@develemit/storefront 0.6.0 → 0.8.0

package/docs/cart.md

@@ -0,0 +1,111 @@
+# Cart and checkout
+
+[← @develemit/storefront](../README.md)
+
+## Cart
+
+Wrap the app in `CartProvider` (inside `StorefrontProvider`). State is a
+snapshot of `CartLine`s; prices and availability are re-verified server-side
+at checkout. Persistence goes through a `CartStorage` (`load`/`save`); the
+default is `localStorageCartStorage(key)`, which hydrates after mount and never
+touches `window` during render.
+
+```tsx
+<CartProvider>
+  <CartButton />
+  <CartDrawer summary={{ onCheckout, checkoutLabel: 'Checkout' }} />
+</CartProvider>
+
+<ProductDetailView
+  product={product}
+  slots={{ actions: <AddToCartButton product={product} /> }}
+/>
+```
+
+`useCart()` exposes `add` (returns `{ added, capped, reason? }`), `remove`,
+`setQuantity`, `clear`, `open`/`close`, and the derived `itemCount` and
+`subtotalCents`. A product's `quantity` is the line's `maxQuantity`, so
+one-of-a-kind items can only be added once. Every label is overridable
+through a `labels` prop; the defaults are exported (`defaultCartDrawerLabels`,
+`defaultCartLineItemLabels`, `defaultAddToCartLabels`, `defaultCheckoutLabels`,
+`defaultCheckoutSuccessLabels`, `defaultAvailabilityLabels`) so you can spread
+and change a few. The pure cart logic (`cartReducer`, `addLine`, `emptyCart`)
+is exported for hosts that keep the cart outside React.
+
+## Checkout
+
+`useCheckout({ startCheckout, onRedirect?, onDiscountInvalid?, labels? })`
+wraps the host's checkout call (a server action or a fetch) and returns
+`{ checkout, busy, message, clearMessage }`. `startCheckout(items, { discountCode })`
+resolves to a `CheckoutResult`: `{ url }`, `{ error: 'out_of_stock', productIds }`
+or `{ error: 'discount_invalid', reason }`. On the server, `toCheckoutResult(error)`
+from `@develemit/storefront/client` maps `CheckoutConflictError` and
+`DiscountInvalidError` to those results (other errors are rethrown). The hook
+removes out-of-stock lines, sets `message`, and redirects with
+`window.location.assign` unless `onRedirect` is given. Copy is overridable
+through `labels` (`outOfStock`, `unavailable`, `discountReasons`).
+
+## Success page
+
+`<CheckoutSuccessView order={order} locale? labels? />` renders an order from
+`getOrderBySession`: lines, subtotal, discount row (only when applied),
+shipping, total, ship-to address (only when you pass an order that includes
+`shippingAddress`; the public order-by-session route never returns it),
+tracking, and a message per `OrderStatus` (`pending` tells the buyer to expect
+an email). It has no hooks, so a server component can render it. Labels live in
+`labels` (including `labels.status`). `<ClearCartOnMount />` empties the cart
+once, even under React strict mode. Styles are `.sf-checkout-success*`.
+
+Extension points, all optional: `slots={{ header, beforeLines, afterTotals,
+actions }}` (ReactNode) put your own content under the heading, above the
+lines, below the totals, and in the footer. `showReference` adds a
+`labels.reference` row (default `Order {id}`; `{id}` becomes the short
+reference such as `#A1B2C3D4`), and `showSummaryHeading` adds an
+`<h2>` from `labels.summaryHeading`. `continueHref` renders a link labelled
+`labels.continue` unless `slots.actions` is given; pass `renderLink` to route it
+through your framework's link (the view uses no hooks, so it can't read the
+provider's).
+
+## Discount codes
+
+`CartSummary` (and `CartDrawer` through `summary`) takes an optional `discount`
+prop. The kit stays framework-agnostic, so the host performs the API call (a
+server action in Next):
+
+```tsx
+<CartDrawer
+  summary={{
+    onCheckout: checkout,
+    discount: {
+      onPreview: async (code, items) => {
+        // call client.previewDiscount; map DiscountInvalidError to a reason
+        return { ok: true, code, discountCents: 480 };
+        // or { ok: false, reason: 'exhausted' }
+      },
+      onApply: (code) => setDiscountCode(code), // null when removed or dropped
+    },
+  }}
+/>
+```
+
+It renders a collapsible "Have a code?" field, a "Discount (CODE) −$4.80" row
+with Remove, and a message for a rejected code. When the cart changes
+(debounced, `debounceMs`, default 300) the code is previewed again and dropped
+with its reason if it no longer applies. Pass the applied code to
+`createCheckout`. `discountReasonMessage(reason, overrides?)` returns the same
+text for a reason, for showing a code rejected at checkout. Override copy with `labels.discount` (`toggle`, `field`,
+`apply`, `remove`, `line`, `unavailable`, and `reasons` per rejection reason).
+
+## Polish hooks
+
+- `CartDrawer` `slots={{ empty, summaryNote }}`: `empty` replaces the
+  `labels.empty` text (for example with a link back to the shop); `summaryNote`
+  renders under the subtotal and Checkout button. An empty cart shows no
+  summary or Checkout button. Close and Remove are at least 44×44px.
+- `CartButton` `icon` (rendered before the label), `labelHidden` (visually
+  hides the label, keeping an accessible name like "Cart, 2 items") and
+  `hideZeroCount` (omits the count at 0; the accessible name becomes
+  "Cart, empty").
+- `--sf-motion-duration` (default `0ms`, no motion) drives the drawer's
+  slide-in and the backdrop's fade, in and out. It is forced to `0ms` under
+  `prefers-reduced-motion: reduce`. Example: `--sf-motion-duration: 200ms`.

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "@develemit/storefront",
-  "version": "0.6.0",
+  "version": "0.8.0",
+  "description": "Brand-agnostic React storefront: components, page views, cart, checkout and a typed API client.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/develemit/develemit-commerce.git",
+    "directory": "packages/storefront"
+  },
+  "homepage": "https://github.com/develemit/develemit-commerce/blob/main/docs/getting-started.md",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -26,7 +33,9 @@
   },
   "files": [
     "dist",
-    "!**/*.tsbuildinfo"
+    "docs",
+    "!**/*.tsbuildinfo",
+    "CHANGELOG.md"
   ],
   "nx": {
     "name": "storefront",
@@ -44,6 +53,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@develemit/commerce-contracts": "0.6.0"
+    "@develemit/commerce-contracts": "0.8.0"
   }
 }