@develemit/storefront 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+## 0.8.0 (2026-11-12)
+
+### Features
+
+- `ProductDetailView` gains `backHref` and `backLabel` (default "Back to the shop") for a link above the gallery. The title is now display-size and bold, the detail column spacing is looser, and a sold product mutes its gallery image like the shop card.
+- **Changed:** `AddToCartButton` renders a non-interactive `.sf-sold-note` span (label `labels.sold`, default "Sold") instead of a disabled button when the product is sold. Reserved products still show the disabled button with `labels.unavailable`.
+- Shop grid: more space between the category chips and the grid, equal-height cards with aligned bodies, and the empty-state content is centred.
+- **Changed:** `CheckoutSuccessView` fills the `labels.reference` `{id}` placeholder with the short reference from `formatOrderRef` (for example `#A1B2C3D4`) instead of the full order id. A custom label that already contains a `#` before `{id}` now shows two; drop it.
+
+## 0.7.0 (2026-11-04)
+
+### Features
+
+- `CheckoutSuccessView` gains `slots` (`header`, `beforeLines`, `afterTotals`, `actions`), `showReference`, `showSummaryHeading`, `continueHref` and `renderLink`, plus the labels `summaryHeading`, `reference` (`{id}` placeholder) and `continue`. All additive; the view still has no hooks.
+
+### Docs
+
+- The package now ships `CHANGELOG.md` and `docs/cart.md` (cart, checkout, success page and discount codes, moved out of the README), and declares `description`, `repository` and `homepage`.
+
+## 0.6.0 (2026-11-03)
+
+No changes; released in lockstep with the other packages.
+
+## 0.5.0 (2026-11-02)
+
+### Features
+
+- `CheckoutSuccessView({ order, locale?, labels?, className? })` renders the order summary for a checkout success page (lines, discount, shipping, total, ship-to address, tracking, per-status message), themed by `--sf-*` tokens with new `.sf-checkout-success*` styles. Exports `CheckoutSuccessLabels` and `defaultCheckoutSuccessLabels`.
+- `ClearCartOnMount` empties the cart once after hydration, safe under React strict mode.
+- `useCheckout({ startCheckout, onRedirect?, onDiscountInvalid?, labels? })` returns `{ checkout, busy, message, clearMessage }`: busy state, removal of out-of-stock lines, discount-reason messages and the gateway redirect. Exports `CheckoutLabels`, `defaultCheckoutLabels`, `StartCheckoutOptions`, `UseCheckoutOptions` and `UseCheckoutValue`.
+- `@develemit/storefront/client` exports `toCheckoutResult(error)` and the `CheckoutResult` / `CheckoutFailure` types, so a server action can turn `CheckoutConflictError` and `DiscountInvalidError` into a serializable result without importing React.
+- Exports `discountReasonMessage(reason, overrides?)`, the same reason text `CartSummary` shows for a rejected code, so hosts can show it when checkout rejects a code (`DiscountInvalidError`).
+
+## 0.4.0 (2026-10-30)
+
+### Features
+
+- `client.previewDiscount({ code, items })` and `createCheckout(items, { discountCode })`, with a new `DiscountInvalidError` (422, carries the rejection `reason`). Exports `CreateCheckoutOptions`.
+- `CartSummary` takes an optional `discount={{ onPreview, onApply, debounceMs }}` prop (also through `CartDrawer`'s `summary`): a collapsible "Have a code?" field, a discount row with Remove, reason messages, and a debounced re-preview that drops a code that stops applying. Labels live under `labels.discount`. Exports `CartSummaryDiscount` and `DiscountPreviewResult`. New `.sf-cart-summary__code*` styles. Needs a server with discounts.
+
+## 0.3.0 (2026-10-30)
+
+### Breaking
+
+- `client.listProducts(query)` returns a page, `{ items: ProductCard[], nextCursor }`, instead of an array, and accepts `limit` and `cursor`. `ProductGrid`, `ProductCard`, `ShopView` and `FeaturedProducts` take the slim `ProductCard` shape (a full `Product` is still assignable).
+
+### Features
+
+- The default `renderImage` now renders `<img loading="lazy" decoding="async">`, or `loading="eager"` with `fetchpriority="high"` when `priority` is set (non-breaking behavior change).
+
+- `ShopView` `nextHref` and `loadMoreLabel` render a server-rendered "Load more" link through `renderLink`; hosts build `nextHref` from `nextCursor`.
+- The "Load more" link now has default `--sf-*` token styling (`.sf-shop__more`, centered in a new `.sf-shop__pager` wrapper).
+- Exports the `ProductCardData` and `ProductCardPage` types (`ProductCardData` avoids clashing with the `ProductCard` component).
+
+### Fixes
+
+- Published tarballs no longer include declaration maps (`*.d.ts.map`), which pointed at `src/` files that were not shipped. JS sourcemaps now embed `sourcesContent`.
+- Built `dist` type resolution: the `client` and `format` entries now emit to `dist/<name>/index.js` beside their declarations, so `allowJs` consumers (Next) get real types instead of `any`. No API change; the `exports` subpaths are unchanged.
+
+## 0.2.0 (2026-10-29)
+
+First published release. 0.1.0 was tagged but never published to npm, so installing 0.2.0 gets everything in both entries below.
+
+### Features
+
+- `CartDrawer` `slots` (`empty`, `summaryNote`) for a custom empty-cart state and a note under the subtotal.
+- `CartButton` `icon`, `labelHidden` and `hideZeroCount` props.
+- `--sf-motion-duration` theme variable (default `0ms`) for drawer slide-in/out and backdrop fade; forced to `0ms` under `prefers-reduced-motion: reduce`. The drawer carries `data-state="open" | "closed"`.
+
+- Catalog presentation hooks: `--sf-card-hover-lift`, `--sf-card-hover-shadow`, `--sf-card-image-hover-scale`, `--sf-sold-opacity`, `--sf-sold-filter`, `--sf-grid-columns-mobile` and `--sf-color-focus` (all default to the current look).
+- `CategoryFilter` `formatLabel` and `sortCategories`; `ShopView` `allLabel`, `formatCategoryLabel` and `sortCategories`.
+- `ShopView`, `FeaturedProducts` and `ProductDetailView` forward `labels` to the availability badge.
+
+### Fixes
+
+- `AvailabilityBadge` is sized to its text (`inline-size: fit-content`) instead of stretching in grid/flex columns.
+- Gallery slide and thumb frames are `position: relative`, so `next/image` `fill` renders correctly; the gallery and thumbs show a `--sf-color-focus` focus ring.
+
+### Behavior changes
+
+- An empty cart no longer renders the summary or a disabled Checkout button.
+- Close is now an icon button (`×`) with `labels.close` as its accessible name, and Close and Remove have a 44×44px minimum target.
+
+## 0.1.0 (2026-10-29)
+
+First release. Brand-agnostic React UI, cart and typed API client. Peers: `react` and `react-dom` `^19`.
+
+### Features
+
+- Catalog components: `PriceTag`, `AvailabilityBadge`, `ProductCard`, `ProductGrid`, `CategoryFilter`, `ProductGallery`.
+- Page views: `ShopView`, `ProductDetailView`, `FeaturedProducts`, `sortForDisplay`.
+- Theme contract: `styles.css` ships the `--sf-*` custom properties; override them to brand the kit.
+- Cart: `CartProvider`, `useCart`, a reducer with localStorage persistence, `AddToCartButton`, `CartDrawer`, `CartLineItem`, `CartSummary` and `CartButton`.
+- `@develemit/storefront/client`: the typed API client (`createCommerceClient`, including `createCheckout` and `getOrderBySession`) and its error types.
+- Image priority: `ImageProps.priority` lets `renderImage` adapters mark above-the-fold images (e.g. `next/image` `priority`). `ProductCard` accepts `priority`, `ProductGrid` accepts `priorityCount` (prioritizes the first N cards; `ShopView` and `FeaturedProducts` use 6), and `ProductGallery` prioritizes the active main image but not the thumbnails.
+- `@develemit/storefront/format`: server-safe entry for `formatPrice` and `sortForDisplay`.
+
+### Notes
+
+- The main bundle is marked `"use client"`. Server components must import pure helpers from `@develemit/storefront/format`.

package/README.md

@@ -1,16 +1,23 @@
 # @develemit/storefront
 
-Brand-agnostic storefront UI and commerce logic, built so it can be extracted
-and published as a standalone package.
+Brand-agnostic storefront UI, cart, checkout and a typed API client for shops
+backed by `@develemit/commerce-server`. New here? Start with the
+[getting-started guide](https://github.com/develemit/develemit-commerce/blob/main/docs/getting-started.md).
+What changed in each version is in [CHANGELOG.md](CHANGELOG.md).
+
+```bash
+pnpm add @develemit/storefront @develemit/commerce-contracts react react-dom
+```
 
 ## Boundary rules
 
 - No client branding, copy, colors, or product data in this package.
   The consuming app supplies those through props, theme tokens, and data adapters.
 - No imports from `apps/*` or other app-specific packages.
-- React, React DOM, and Next are peer dependencies, never bundled.
+- React and React DOM are peer dependencies, never bundled. Next is optional:
+  it is wired in through the adapters below, never imported.
 
-## Commands
+## Developing this package
 
 - `pnpm exec nx build storefront` — library build to `packages/storefront/dist`
 - `pnpm exec nx test storefront`
@@ -49,7 +56,8 @@ the variables in the host app (or pass a `StorefrontTheme` through
 `PriceTag`, `AvailabilityBadge`, `ProductCard`, `ProductGrid`,
 `CategoryFilter`, and `ProductGallery` are styled only through the `--sf-*`
 variables. Wrap them in `StorefrontProvider` to supply framework adapters;
-without it they fall back to plain `<a>` and `<img>`.
+without it they fall back to plain `<a>` and `<img>`. `useStorefront()` reads
+the provider's config (locale, adapters, hrefs) in your own components.
 
 Example Next.js host setup (host code, not part of this package):
 
@@ -215,97 +223,11 @@ export default async function ProductPage({
 }
 ```
 
-## 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.
-
-### 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 (when the order includes `shippingAddress`),
-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*`.
-
-### 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
-    },
-  }}
-/>
-```
+## Cart and checkout
 
-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`. 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`.
+`CartProvider`, `CartButton`, `CartDrawer`, `AddToCartButton`, `useCart`,
+`useCheckout`, `CheckoutSuccessView`, `ClearCartOnMount` and discount codes are
+documented in [docs/cart.md](docs/cart.md).
 
 ### Catalog presentation hooks
 

package/dist/components/add-to-cart-button/add-to-cart-button.d.ts

@@ -3,6 +3,7 @@ export interface AddToCartLabels {
     add: string;
     inCart: string;
     unavailable: string;
+    sold: string;
 }
 export declare const defaultAddToCartLabels: AddToCartLabels;
 export interface AddToCartButtonProps {

package/dist/components/checkout-success/checkout-success-view.d.ts

@@ -1,3 +1,4 @@
+import { ReactNode } from 'react';
 import { OrderAddress, OrderSummary } from '@develemit/commerce-contracts';
 import { CheckoutSuccessLabels } from './labels';
 export interface CheckoutSuccessViewProps {
@@ -9,5 +10,19 @@ export interface CheckoutSuccessViewProps {
         status?: Partial<CheckoutSuccessLabels['status']>;
     };
     className?: string;
+    slots?: {
+        header?: ReactNode;
+        beforeLines?: ReactNode;
+        afterTotals?: ReactNode;
+        actions?: ReactNode;
+    };
+    showReference?: boolean;
+    showSummaryHeading?: boolean;
+    continueHref?: string;
+    renderLink?: (props: {
+        href: string;
+        children: ReactNode;
+        className?: string;
+    }) => ReactNode;
 }
-export declare function CheckoutSuccessView({ order, locale, labels, className, }: CheckoutSuccessViewProps): import('react').JSX.Element;
+export declare function CheckoutSuccessView({ order, locale, labels, className, slots, showReference, showSummaryHeading, continueHref, renderLink, }: CheckoutSuccessViewProps): import('react').JSX.Element;

package/dist/components/checkout-success/labels.d.ts

@@ -1,6 +1,9 @@
 import { OrderStatus } from '@develemit/commerce-contracts';
 export interface CheckoutSuccessLabels {
     heading: string;
+    summaryHeading: string;
+    reference: string;
+    continue: string;
     subtotal: string;
     discount: string;
     shipping: string;