- `, its lines are `role="listitem"` elements, and the drawer panel sits inside a positioning element.
diff --git a/packages/commerce-storefront/README.md b/packages/commerce-storefront/README.md
index f92bd142..073b35c0 100644
--- a/packages/commerce-storefront/README.md
+++ b/packages/commerce-storefront/README.md
@@ -54,11 +54,12 @@ Use the providers your application already has; do not create another router or
| `catalogPath` | `/shop` | Same-origin catalog route |
| `productPath` | `/products` | Same-origin prefix for product links; register `${productPath}/:productId` |
| `checkoutSuccessPath` | unset | Same-origin return route; enables checkout UI only when supplied |
+| `onItemAdded` | unset | Called with `{ name, quantity, isSample }` after each add, live or sample; use it to confirm adds on a site with a cart page instead of a drawer |
| `theme` | inherited text and transparent wrappers; neutral control palette | CSS custom properties applied to storefront surfaces and the portalled drawer |
Provide root-relative paths without a trailing slash. Enable `checkoutSuccessPath` only after your server supports checkout and validates merchant readiness. Mount a corresponding return page. A redirect back from checkout is **not proof of payment**; that page must obtain authoritative payment status from your server. This package does not provide a payment receipt page or merchant onboarding.
-`GET /api/commerce/config` supplies the currency and opaque cart scope. The scope must change when the store, channel, or currency binding changes. The draft-order cart displays its subtotal and explains that shipping, taxes, and discounts are calculated at checkout. The explanation has the stable `commerce-cart-checkout-adjustments-note` class so applications can hide it when needed. The cart does not create a checkout session or calculate adjustments. Applications do not pass store IDs or credentials into the browser package. One storefront binding is supported per page and query client.
+`GET /api/commerce/config` supplies the currency and opaque cart scope. The scope must change when the store, channel, or currency binding changes. The draft-order cart displays its subtotal and explains that shipping, taxes, and discounts are calculated at checkout. The explanation's outer element has the stable `commerce-cart-checkout-adjustments-note` class so applications can hide it when needed. The cart does not create a checkout session or calculate adjustments. Applications do not pass store IDs or credentials into the browser package. One storefront binding is supported per page and query client.
A connection failure leaves the surrounding application and its state mounted. Catalog and product surfaces show the connection error and retry action. Custom integrations can render `CommerceStatus` or inspect `useCommerce().connection`.
@@ -78,15 +79,15 @@ A connection failure leaves the surrounding application and its state mounted. C
}}
>
{/* Register /collection and /item/:productId in your router. */}
-
- {isSample ? 'Sample subtotal' : 'Subtotal'} +
- {money(subtotal, currency)} +
-
- - {item.image && ( --
- )} -
--{item.name}
- {item.options?.map((option) => ( -- {option.attribute}: {option.values?.join(', ')} -
- ))} -- {typeof item.subtotal === 'number' - ? money(item.subtotal, item.currency ?? currency) - : 'Price unavailable'} -
---- - - Quantity: - {item.quantity} - - -- -
- ))}
- - {isSample ? 'Sample subtotal' : 'Subtotal'} -
- - {money( - subtotal, - isSample ? 'USD' : (cart?.totals?.subTotal?.currencyCode ?? currency), - )} - -
`, keep the package's own styles: a host font size on `ProductDetailsTitle` does not change the heading's size, but a host color does reach it, because the heading inherits its color.
+Your own elements inside a root are a limit for now. The package's unlayered reset matches every element inside a root that is not a part's outer element, so layered host styles lose there:
+- **Color, font family and border** on any element.
+- **Margin, padding, font size and weight** on headings, paragraphs, lists and fieldsets.
+- **Font, color, background and border radius** on buttons, inputs and selects. Custom controls such as the swatches below are affected.
+
+Until the package scopes its reset, you can work around it:
+- Keep page headings outside the root.
+- Put colors on a part's `className`, which its children inherit.
+- Mark the affected declarations `!important`; a layered `!important` beats unlayered CSS.
+
+A part that renders nothing, such as `ProductDetailsAvailability` before a SKU is verified, leaves no grid cell, so the cells after it move up in a host grid. Wrap such parts in your own element or use named grid areas.
+
Two hooks support custom parts inside the root:
- `useProductDetails()` returns read-only `product`, `name`, `selectedSku`, `quantity`, `availableQuantity`, `images` and `status` (`incomplete`, `checking`, `variant-error`, `unavailable`, `not-purchasable` or `ready`). `selectedSku` is set only when `status` is `ready`.
@@ -223,10 +238,100 @@ As with product layouts, the grid, spacing and border classes come from your own
| `ProductCardDescription`, `ProductCardPrice` | Up to three lines of description (nothing without one), and the price or price range |
| `ProductCardAction` | Adds the product directly only when it has one SKU and no options; otherwise links to the product page to choose |
-`className` on `CatalogProducts` goes on the element whose direct children are the cards, so a host grid places them, and `className` on `ProductCardRoot` goes on each card, so classes such as `col-span-2` work. The loading placeholder (three cards, one to three columns), the error with its retry button, and the empty message render just before that element, whatever the layout. Card parts take no product, SKU or price props. Inside `CatalogProducts`, `ProductCardRoot` takes no `product` prop either and throws if it gets one, so a card always shows the product it is rendered for. Samples use the same card: they show a placeholder image, no description and no links, and add only to the sample cart. Card and catalog parts throw if they are rendered outside their root. Packaged cards fill their grid row, with the price and action at the bottom of each card.
+`className` on `CatalogProducts` goes on the element whose direct children are the cards, so a host grid places them, and `className` on `ProductCardRoot` goes on each card, so classes such as `col-span-2` work. While products load, that element holds three placeholder cards, so they follow the host's grid. The error with its retry button and the empty message render just before it. Card parts take no product, SKU or price props. Inside `CatalogProducts`, `ProductCardRoot` takes no `product` prop either and throws if it gets one, so a card always shows the product it is rendered for. Samples use the same card: they show a placeholder image, no description and no links, and add only to the sample cart. Card and catalog parts throw if they are rendered outside their root. Packaged cards fill their grid row, with the price and action at the bottom of each card.
For a product the host already has, such as a featured product, use `ProductCard` or `ProductCardRoot` with a `product` prop outside the catalog. `useProductCard()` returns read-only `product` (`null` for samples), `name`, `href` (`null` for samples) and `isSample` for building custom card parts. Every part accepts `className` on an outer wrapper that the package's CSS reset leaves alone, with the same limits as [product parts](#custom-product-layouts).
+## Custom cart layouts
+
+`CartDrawer` is the recommended cart. `CommerceStorefront` mounts it. When its layout does not fit, use `CommerceProvider` and mount your own `CartDrawerRoot` once in its place. Development builds warn when more than one drawer is mounted, because every add would open all of them. It opens when an item is added or a `CartButton` is pressed and returns focus when it closes, like the packaged drawer. This is `CartDrawer` written out:
+
+```tsx
+import {
+ CartCheckout, CartCheckoutNote, CartClose, CartDescription, CartDrawerRoot, CartEmpty, CartItemImage, CartItemName,
+ CartItemOptions, CartItemPrice, CartItemQuantity, CartItemRemove, CartItemRoot, CartItems, CartNotices, CartSubtotal,
+ CartSummary, CartTitle, CommerceProvider,
+} from '@godaddy/gd-commerce-storefront';
+
+
+ {/* Header and routes */}
+
+
+
+
+
+
+
+
+
+
+
+
+```
+
+`className` on `CartDrawerRoot` goes on the dialog panel, which sits at the right edge at full height. The packaged width, background and column layout are the classes above; without them the panel is only as wide as its content and has no background. Add `mr-auto` to open it from the left. Keep `CartTitle` in a drawer: it names the dialog, and the dialog library logs an error without it. `CartDescription` is optional and describes the dialog when present. Render each of them once per drawer, because they use the dialog's own element IDs.
+
+For a cart page instead of, or as well as, the drawer, compose the same parts inside `CartRoot` on a route such as `/cart`. It shows the connection state itself, and `CartClose` renders nothing there. If the site has no drawer, use `CommerceProvider` without `CartDrawerRoot` and link to the page instead of rendering `CartButton`. Adds then open nothing, and `useCommerce().open` stays `false`. Confirm adds with the provider's `onItemAdded`, for example with a toast that links to the cart.
+
+```tsx
+Your cart
+
+
+
+
+
+```
+
+| Part | Renders |
+| --- | --- |
+| `CartTitle`, `CartDescription` | "Your cart" as an H2 and one line about it; sample wording before a store is connected |
+| `CartClose` | The drawer's close button; nothing outside the drawer |
+| `CartNotices` | A storage warning, and a cart error with a refresh button; nothing when there are neither |
+| `CartItems` | The cart lines as a list. Its child is the item, rendered once for each line; without one, the packaged item. "Loading your cart…" renders just before the list while the saved cart loads |
+| `CartItemImage`, `CartItemName`, `CartItemOptions`, `CartItemPrice` | The line's image (nothing without one), name as an H3, selected options (nothing without any) and line total |
+| `CartItemQuantity`, `CartItemRemove` | Decrease and increase buttons around the quantity, and the remove button |
+| `CartEmpty` | Only when the cart is empty: a message and a link to the catalog, or its own children instead |
+| `CartSummary` | A container that renders only when the cart has items |
+| `CartSubtotal`, `CartCheckoutNote` | The subtotal, and the note that shipping, taxes and discounts come at checkout. The note's outer element keeps the `commerce-cart-checkout-adjustments-note` class |
+| `CartCheckout` | The checkout button when `checkoutSuccessPath` is set; otherwise a message that checkout is unavailable. Samples never check out |
+
+`className` on `CartItems` goes on the list element whose direct children are the items, and `className` on `CartItemRoot` goes on each item. The list is a `role='list'` element rather than a ``, so it has no browser margin or indent for a package rule to reset. Cart and item parts take no item, quantity or price props, and they throw if they are rendered outside their root. In development builds, an item template without a `CartItemRoot` logs a warning, because the list would have no items. `CartItemImage` and `CartItemOptions` render nothing for a line without an image or options, which moves the line's other cells in a host grid. Every cart action goes through the shared provider's queue, whatever the layout, and while no store is connected the parts show the sample cart, which never reaches the store. Every part accepts `className` on an outer wrapper that the package's CSS reset leaves alone, with the same limits as [product parts](#custom-product-layouts).
+
+Two hooks support custom cart markup:
+
+- `useCart()` works anywhere inside `CommerceProvider`. It returns read-only `items`, `itemCount`, `subtotal` (minor units, or `null` when the server has not priced the cart), `currency`, `isSample` and `loading`. Combine `itemCount` with `useCommerce().setOpen(true)` for a custom cart button.
+- `useCartItem()` returns the line inside `CartItemRoot`: `id`, `name`, `quantity`, `imageUrl`, `options`, `subtotal` and `currency`.
+
## How it works
Products are SKU groups. The package purchases only an unambiguous SKU, verifies all selected attributes through the server, uses SKU prices/images, and distinguishes untracked inventory from sold-out inventory. Server-side inventory and pricing checks remain mandatory.
diff --git a/packages/commerce-storefront/src/cart-parts.test.tsx b/packages/commerce-storefront/src/cart-parts.test.tsx
new file mode 100644
index 00000000..f42adfd1
--- /dev/null
+++ b/packages/commerce-storefront/src/cart-parts.test.tsx
@@ -0,0 +1,712 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { act, render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { Component, type ErrorInfo, type ReactElement, type ReactNode, useState } from 'react';
+import { MemoryRouter, Route, Routes } from 'react-router';
+import { describe, expect, it, vi } from 'vitest';
+import { AddToCartButton, CartButton } from './cart';
+import type { CartOrder } from './cart-model';
+import {
+ CartCheckout,
+ CartCheckoutNote,
+ CartClose,
+ CartDescription,
+ CartDrawer,
+ CartDrawerRoot,
+ CartEmpty,
+ CartItemImage,
+ CartItemName,
+ CartItemOptions,
+ CartItemPrice,
+ CartItemQuantity,
+ CartItemRemove,
+ CartItemRoot,
+ CartItems,
+ CartNotices,
+ CartRoot,
+ CartSubtotal,
+ CartSummary,
+ CartTitle,
+ useCartItem,
+} from './cart-parts';
+import { useCart } from './cart-state';
+import { Catalog, CatalogProducts, CatalogRoot } from './catalog';
+import { CommerceProvider, type CommerceProviderProps, useCommerce } from './commerce-provider';
+import { CommerceStorefront } from './commerce-storefront';
+import { packageRuleConflicts } from './test-css';
+
+const response = (body: unknown, status = 200) => new Response(JSON.stringify(body), { status });
+const storageKey = 'godaddy:commerce-storefront:cart:s';
+
+function order(lines: { id: string; name: string; quantity: number; price: number }[]): CartOrder {
+ const subtotal = lines.reduce((sum, line) => sum + line.price * line.quantity, 0);
+ return {
+ id: 'cart-1',
+ lineItems: lines.map((line) => ({
+ id: line.id,
+ name: line.name,
+ quantity: line.quantity,
+ details: {
+ productAssetUrl: line.id === 'line-1' ? 'https://cdn.test/mug.png' : null,
+ selectedOptions: line.id === 'line-2' ? [{ attribute: 'Size', values: ['M'] }] : null,
+ },
+ totals: { subTotal: { value: line.price * line.quantity, currencyCode: 'USD' } },
+ })),
+ totals: {
+ subTotal: { value: subtotal, currencyCode: 'USD' },
+ total: { value: subtotal, currencyCode: 'USD' },
+ },
+ };
+}
+
+/** A connected store with a saved cart of two lines that accepts quantity changes and removals. */
+function mockStore({ state = 'ready' }: { state?: string } = {}) {
+ localStorage.setItem(storageKey, 'cart-1');
+ let lines = [
+ { id: 'line-1', name: 'Mug', quantity: 2, price: 1200 },
+ { id: 'line-2', name: 'Shirt', quantity: 1, price: 2500 },
+ ];
+ const fn = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+ const url = new URL(String(input), 'https://host.test');
+ if (url.pathname.endsWith('/config'))
+ return response(state === 'ready' ? { cartScope: 's', currencyCode: 'USD' } : { state });
+ const line = url.pathname.match(/\/items\/([^/]+)$/)?.[1];
+ if (line && init?.method === 'PATCH') {
+ const { quantity } = JSON.parse(String(init.body));
+ lines = lines.map((candidate) => (candidate.id === line ? { ...candidate, quantity } : candidate));
+ }
+ if (line && init?.method === 'DELETE') lines = lines.filter((candidate) => candidate.id !== line);
+ if (url.pathname.endsWith('/checkout')) return response({ url: 'https://pay.test/session' });
+ if (url.pathname.endsWith('/products'))
+ return response({ skuGroups: { edges: [], pageInfo: { hasNextPage: false } } });
+ return response({ cart: order(lines) });
+ });
+ vi.stubGlobal('fetch', fn);
+ return fn;
+}
+
+function app(children: ReactNode, props: Partial = {}, path = '/cart'): ReactElement {
+ return (
+
+
+ {children}
+
+
+ );
+}
+
+function OpenCart(): ReactElement {
+ const { setOpen } = useCommerce();
+ return (
+
+ );
+}
+
+function LineBadge(): ReactElement {
+ const { name, quantity } = useCartItem();
+ return ;
+}
+
+describe('composable cart', () => {
+ it('builds a custom drawer from parts, edits lines, and checks out', async () => {
+ const api = mockStore();
+ const assign = vi.fn();
+ vi.stubGlobal('location', { ...window.location, origin: 'https://shop.test', assign });
+ render(
+ app(
+ <>
+
+
+
+
+
+
+
+
+ ,
+ { checkoutSuccessPath: '/thanks' },
+ ),
+ );
+ await userEvent.click(await screen.findByRole('button', { name: 'Open' }));
+ const dialog = await screen.findByRole('dialog', { name: 'Your cart' });
+ expect(dialog).toHaveClass('host-panel');
+ // Without a CartDescription the dialog names no description, so Radix has nothing to warn about.
+ expect(dialog).not.toHaveAttribute('aria-describedby');
+ await waitFor(() => expect(within(dialog).getAllByTestId('line')).toHaveLength(2));
+ const lines = within(dialog).getAllByRole('listitem');
+ expect(lines[0]).toHaveClass('host-line');
+ expect(lines[0].parentElement).toHaveClass('host-list');
+ expect(
+ within(dialog)
+ .getAllByTestId('line')
+ .map((line) => line.textContent),
+ ).toEqual(['Mug×2', 'Shirt×1']);
+ expect(within(dialog).getByText('$49.00')).toBeVisible();
+
+ await userEvent.click(within(dialog).getByRole('button', { name: 'Increase quantity of Mug' }));
+ await waitFor(() => expect(within(dialog).getByText('Mug×3')).toBeInTheDocument());
+ const patch = api.mock.calls.find((call) => call[1]?.method === 'PATCH');
+ expect(String(patch?.[0])).toBe('/api/commerce/cart/cart-1/items/line-1');
+ expect(JSON.parse(String(patch?.[1]?.body))).toEqual({ quantity: 3 });
+
+ await userEvent.click(within(dialog).getByRole('button', { name: 'Remove Shirt' }));
+ await waitFor(() => expect(within(dialog).getAllByTestId('line')).toHaveLength(1));
+ expect(within(dialog).getByRole('button', { name: 'Decrease quantity of Mug' })).toBeEnabled();
+
+ await userEvent.click(within(dialog).getByRole('button', { name: 'Proceed to Checkout' }));
+ await waitFor(() => expect(assign).toHaveBeenCalledWith('https://pay.test/session'));
+ await userEvent.click(within(dialog).getByRole('button', { name: 'Close cart' }));
+ await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument());
+ });
+
+ it('links the description only while one is rendered', async () => {
+ mockStore();
+ const warn = vi.spyOn(console, 'warn');
+ render(
+ app(
+ <>
+
+
+ ,
+ ),
+ );
+ await userEvent.click(await screen.findByRole('button', { name: 'Open' }));
+ const dialog = await screen.findByRole('dialog', { name: 'Your cart' });
+ await waitFor(() => expect(dialog).toHaveAccessibleDescription('Review your items before checkout.'));
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('shows the cart on a page, with a custom empty state and no close button', async () => {
+ mockStore();
+ render(
+ app(
+
+
+ Cart
+
+ Nothing here yet.
+
+
+
+
+ }
+ />
+ ,
+ ),
+ );
+ const title = await screen.findByRole('heading', { level: 2, name: 'Your cart' });
+ expect(title.closest('section')).toHaveClass('host-page');
+ expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Close cart' })).not.toBeInTheDocument();
+ expect(await screen.findByRole('heading', { level: 3, name: 'Mug' })).toBeVisible();
+ // The packaged item shows the image and options.
+ expect(document.querySelector('img[src="https://cdn.test/mug.png"]')).not.toBeNull();
+ expect(screen.getByText('Size: M')).toBeVisible();
+ expect(screen.getByText('Checkout is not available yet.')).toBeVisible();
+ for (const name of ['Remove Mug', 'Remove Shirt']) {
+ await userEvent.click(screen.getByRole('button', { name }));
+ await waitFor(() => expect(screen.queryByRole('button', { name })).not.toBeInTheDocument());
+ }
+ expect(screen.getByText('Nothing here yet.')).toBeVisible();
+ expect(screen.queryByText('Subtotal')).not.toBeInTheDocument();
+ expect(
+ screen.queryByText('Shipping, taxes, and discounts are calculated at checkout.'),
+ ).not.toBeInTheDocument();
+ });
+
+ it('shows the sample cart on a page and never sends it to the store', async () => {
+ const api = mockStore({ state: 'unbound' });
+ render(
+ app(
+ <>
+
+
+
+
+
+
+ ,
+ ),
+ );
+ const title = await screen.findByRole('heading', { level: 2, name: 'Sample cart' });
+ const page = title.closest('section') as HTMLElement;
+ expect(page).toHaveAttribute('data-commerce-source', 'sample');
+ expect(within(page).getByRole('link', { name: 'Browse products' })).toHaveAttribute('href', '/shop');
+ await userEvent.click(screen.getByRole('button', { name: 'Add Product 2 to sample cart' }));
+ expect(await within(page).findByRole('heading', { level: 3, name: 'Product 2' })).toBeVisible();
+ expect(within(page).getByText('Sample subtotal')).toBeVisible();
+ expect(within(page).getByText('Example total in USD. Checkout is not set up yet.')).toBeVisible();
+ expect(within(page).queryByText(/calculated at checkout/)).not.toBeInTheDocument();
+ await userEvent.click(within(page).getByRole('button', { name: 'Increase quantity of Product 2' }));
+ // The line and the subtotal.
+ expect(within(page).getAllByText('$40.00')).toHaveLength(2);
+ expect(api.mock.calls.every(([input]) => String(input).endsWith('/config'))).toBe(true);
+ });
+
+ it('keeps host classes on the connection status', () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(() => new Promise(() => {})),
+ );
+ render(
+ app(
+
+ ,
+ ),
+ );
+ expect(screen.getByText('Connecting to the store…').closest('.host-page')).not.toBeNull();
+ });
+
+ it('shows a storage warning and a refreshable error together', async () => {
+ mockStore();
+ vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+ throw new Error('quota');
+ });
+ let fail = true;
+ const api = vi.mocked(fetch);
+ const store = api.getMockImplementation();
+ api.mockImplementation(async (input, init) => {
+ if (String(input).endsWith('/cart/cart-1') && fail) return response({ error: 'Cart offline' }, 503);
+ return store?.(input, init) as Promise;
+ });
+ render(
+ app(
+
+ ,
+ ),
+ );
+ const alert = await screen.findByRole('alert');
+ expect(alert).toHaveTextContent('Cart offline');
+ expect(alert.closest('.host-notices')).not.toBeNull();
+ fail = false;
+ await userEvent.click(within(alert).getByRole('button', { name: 'Refresh cart' }));
+ await waitFor(() => expect(screen.queryByRole('alert')).not.toBeInTheDocument());
+ expect(
+ await screen.findByText('Your browser cannot save the cart. Keep this page open while shopping.'),
+ ).toBeVisible();
+ });
+
+ it('counts the cart for a custom cart button', async () => {
+ mockStore();
+ function CustomButton(): ReactElement {
+ const { itemCount, loading } = useCart();
+ return ;
+ }
+ render(
+ app(
+ <>
+ or .',
+ );
+ expect(() => render(app(.',
+ );
+ function Orphan(): null {
+ useCartItem();
+ return null;
+ }
+ expect(() => render(app(.');
+ });
+
+ it('names CartItems when an item is rendered outside it', async () => {
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+ mockStore();
+ const errors: unknown[] = [];
+ render(
+ app(
+
+
+
+
+
+ ,
+ ),
+ );
+ await waitFor(() => expect(errors).toHaveLength(1));
+ expect(String(errors[0])).toContain('CartItemRoot must be rendered inside .');
+ });
+
+ it('puts host classes on an element that no package rule styles', async () => {
+ mockStore();
+ const conflicts = packageRuleConflicts();
+ render(
+ app(
+ <>
+
+
+
+
+
+
+
+
+
+
+ ,
+ ),
+ );
+ await userEvent.click(await screen.findByRole('button', { name: 'Open' }));
+ await screen.findByRole('heading', { level: 3, name: 'Shirt' });
+ // Drawer, title, description, close, list, summary, subtotal, note, checkout, page root; per line: the root,
+ // name, price, quantity and remove, plus the mug's image and the shirt's options.
+ expect(document.querySelectorAll('.host')).toHaveLength(10 + 2 * 5 + 2);
+ for (const host of document.querySelectorAll('.host')) {
+ const part = host.localName + [...host.classList].filter((name) => name !== 'host').join('.');
+ expect({ part, conflicts: conflicts(host) }).toEqual({ part, conflicts: [] });
+ }
+ });
+
+ it('checks the notices and empty state for package rules too', async () => {
+ mockStore();
+ const store = vi.mocked(fetch).getMockImplementation();
+ vi.mocked(fetch).mockImplementation(async (input, init) =>
+ String(input).endsWith('/cart/cart-1')
+ ? response({ error: 'Cart offline' }, 503)
+ : (store?.(input, init) as Promise),
+ );
+ const conflicts = packageRuleConflicts();
+ render(
+ app(
+
+ ,
+ ),
+ );
+ await screen.findByText('Cart offline');
+ expect(document.querySelectorAll('.host')).toHaveLength(2);
+ for (const host of document.querySelectorAll('.host')) expect(conflicts(host)).toEqual([]);
+ });
+
+ it('falls back to the default empty state when its children render nothing', async () => {
+ mockStore();
+ vi.mocked(fetch).mockImplementation(async (input) =>
+ String(input).endsWith('/config')
+ ? response({ cartScope: 's', currencyCode: 'USD' })
+ : response({ cart: null }),
+ );
+ localStorage.clear();
+ const custom = false;
+ render(
+ app(
+
+ {custom && Custom
}
+ ,
+ ),
+ );
+ expect(await screen.findByText('Your cart is empty')).toBeVisible();
+ expect(screen.getByRole('link', { name: 'Browse products' })).toBeVisible();
+ });
+
+ it('warns when the item template renders no CartItemRoot', async () => {
+ mockStore();
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ render(
+ app(
+
+
+ line
+
+ ,
+ ),
+ );
+ await waitFor(() => expect(screen.getAllByText('line')).toHaveLength(2));
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('renders no '));
+ warn.mockClear();
+ render(
+ app(
+
+ ,
+ ),
+ );
+ await screen.findAllByRole('heading', { level: 3, name: 'Mug' });
+ expect(warn).not.toHaveBeenCalled();
+ });
+
+ it('warns when more than one drawer is mounted', () => {
+ mockStore();
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ render(
+ app(
+ <>
+
+
+ ,
+ ),
+ );
+ expect(warn).toHaveBeenCalledWith(expect.stringContaining('More than one cart drawer is mounted'));
+ });
+
+ it('opens a drawer on add only when one is mounted, and reports every add', async () => {
+ mockStore();
+ const added = vi.fn();
+ function Open(): ReactElement {
+ const { open } = useCommerce();
+ return ;
+ }
+ const sku = { id: 'sku-mug' };
+ const view = render(
+ app(
+ <>
+
+
+ ,
+ { onItemAdded: added },
+ ),
+ );
+ await userEvent.click(await screen.findByRole('button', { name: 'Add to cart' }));
+ expect(await screen.findByRole('dialog', { name: 'Your cart' })).toBeVisible();
+ expect(added).toHaveBeenCalledTimes(2);
+ });
+
+ it('reports sample adds too', async () => {
+ mockStore({ state: 'unbound' });
+ const added = vi.fn();
+ render(
+ app(
+
+ ,
+ { onItemAdded: added },
+ ),
+ );
+ await userEvent.click(await screen.findByRole('button', { name: 'Add Product 2 to sample cart' }));
+ expect(added).toHaveBeenCalledWith({ name: 'Product 2', quantity: 1, isSample: true });
+ });
+
+ it('renders the packaged drawer from CommerceStorefront with dividers between lines', async () => {
+ mockStore();
+ render(
+
+
+
+
+
+ ,
+ );
+ await userEvent.click(await screen.findByRole('button', { name: 'Open' }));
+ const dialog = await screen.findByRole('dialog', { name: 'Your cart' });
+ expect(dialog).toHaveAccessibleDescription('Review your items before checkout.');
+ await within(dialog).findByRole('heading', { level: 3, name: 'Shirt' });
+ // The reset skips part elements, so the list's divider reaches each line.
+ expect(getComputedStyle(within(dialog).getAllByRole('listitem')[0]).borderBottomWidth).not.toBe('0px');
+ });
+});
+
+describe('add to cart reasons', () => {
+ const mug = (quantity: number) => ({
+ id: 'sku-mug',
+ inventoryCounts: { edges: [{ node: { type: 'AVAILABLE', quantity } }] },
+ });
+
+ it('says why the button is disabled', async () => {
+ mockStore();
+ function Harness(): ReactElement {
+ const [quantity, setQuantity] = useState(5);
+ const [stock, setStock] = useState(3);
+ return (
+ <>
+ ((done) => {
+ finish = done;
+ });
+ return response({ skuGroups: { edges: [], pageInfo: { hasNextPage: false } } });
+ }
+ return response({ cart: null });
+ }),
+ );
+ render(
+ app(
+
+ ,
+ ),
+ );
+ await waitFor(() =>
+ expect(document.querySelectorAll('.host-grid > [aria-hidden="true"]')).toHaveLength(3),
+ );
+ await act(async () => finish());
+ expect(await screen.findByText('No products available.')).toBeVisible();
+ expect(document.querySelector('.host-grid')?.children).toHaveLength(0);
+ });
+
+ it('still render for the packaged catalog', async () => {
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async (input: RequestInfo | URL) =>
+ String(input).endsWith('/config')
+ ? response({ cartScope: 's', currencyCode: 'USD' })
+ : new Promise(() => {}),
+ ),
+ );
+ render(app(`. */
+ action: string | null;
+ /** Any cart action, from here or anywhere else, is running. */
+ locked: boolean;
+ run: (action: string, operation: () => Promise) => void;
+ changeQuantity: (itemId: string, quantity: number) => Promise;
+ removeItem: (itemId: string) => Promise;
+ refresh: () => Promise;
+ checkout: () => Promise;
+ close: () => void;
+}
+
+const CartContext = createContext(null);
+const CartDrawerContext = createContext(null);
+
+function useCartInternal(part: string): CartInternal {
+ const context = useContext(CartContext);
+ if (!context) throw new Error(`${part} must be rendered inside or .`);
+ return context;
+}
+
+function CartProvider({ children }: { children: ReactNode }): ReactElement {
+ const commerce = useCommerce();
+ const sample = useSampleCart();
+ const state = useCart();
+ const [action, setAction] = useState(null);
+ // Not memoized: the commerce context value is new on every provider render, so a memo would never hit.
+ const locked: boolean = commerce.pending || commerce.hydrating || action !== null;
+ const value: CartInternal = {
+ ...state,
+ hydrating: commerce.hydrating,
+ error: commerce.error,
+ storageWarning: commerce.storageWarning,
+ catalogPath: commerce.config.catalogPath,
+ checkoutEnabled: !!commerce.config.checkoutSuccessPath,
+ checkoutReady: commerce.cart?.totals?.total?.value != null,
+ action,
+ locked,
+ run: (next, operation) => {
+ if (locked) return;
+ setAction(next);
+ void operation().finally(() => setAction(null));
+ },
+ changeQuantity: state.isSample ? sample.changeQuantity : commerce.changeQuantity,
+ removeItem: state.isSample ? sample.remove : commerce.removeItem,
+ refresh: commerce.refresh,
+ checkout: commerce.checkout,
+ close: () => commerce.setOpen(false),
+ };
+ return {children} ;
+}
+
+export interface CartRootProps {
+ children: ReactNode;
+ /** Added to the root ``. */
+ className?: string;
+}
+
+/**
+ * Provides the cart to cart parts on a page, such as a `/cart` route. While no store is connected it shows the sample
+ * cart. Use `CartDrawerRoot` for the drawer.
+ */
+export function CartRoot({ children, className }: CartRootProps): ReactElement {
+ const { connection } = useCommerce();
+ const isSample: boolean = connection === 'unbound';
+ return (
+
+ {connection === 'ready' || isSample ? (
+
+
+ {children}
+
+
+ ) : (
+ // Host classes stay on while connecting, so the layout does not jump when the cart replaces the status.
+
+
+ );
+}
+
+export interface CartDrawerRootProps {
+ children: ReactNode;
+ /** Added to the drawer panel. The packaged drawer passes its width, background and column layout here. */
+ className?: string;
+}
+
+/**
+ * The cart dialog. Opens when an item is added or a `CartButton` is pressed, and returns focus when it closes.
+ * The panel sits at the right edge at full height; `mr-auto` on it moves it to the left. Mount one per provider,
+ * in place of `CartDrawer`.
+ */
+export function CartDrawerRoot({ children, className }: CartDrawerRootProps): ReactElement {
+ const { open, setOpen, restoreFocus, connection } = useCommerce();
+ // Adds open the drawer only while one is mounted, so a site with a cart page gets no stuck `open` state.
+ const registerDrawer = useContext(CartDrawerRegistry);
+ useEffect(() => registerDrawer?.(), [registerDrawer]);
+ // Radix links its description by default. Radix 1.1 also does so with none mounted, then warns about the missing
+ // element, so `aria-describedby={undefined}` turns the link off until a `CartDescription` mounts. Without the
+ // override, each Radix version links its own description ID.
+ const [described, setDescribed] = useState(false);
+ const { register, has } = usePartRegistry(
+ useCallback((registered: PartRegistry['has']) => setDescribed(registered('description')), []),
+ );
+ useEffect(() => {
+ setDescribed(has('description'));
+ }, [has]);
+ const drawer = useMemo((): CartDrawerInternal => ({ register }), [register]);
+ return (
+
+
+
+ {
+ event.preventDefault();
+ restoreFocus();
+ }}
+ >
+
+ {children}
+
+
+
+
+
+
+ );
+}
+
+/** "Your cart", or "Sample cart" before a store is connected, as an H2. In the drawer it names the dialog. */
+export function CartTitle({ className }: CartPartProps): ReactElement {
+ const { isSample } = useCartInternal('CartTitle');
+ const Heading = useContext(CartDrawerContext) ? Dialog.Title : 'h2';
+ return (
+
+ {isSample ? 'Sample cart' : 'Your cart'}
+
+ );
+}
+
+/** One line about the cart. In the drawer it describes the dialog. */
+export function CartDescription({ className }: CartPartProps): ReactElement {
+ const { isSample } = useCartInternal('CartDescription');
+ const drawer = useContext(CartDrawerContext);
+ const register = drawer?.register;
+ useEffect(() => register?.('description'), [register]);
+ const text: string = isSample
+ ? 'Example products and prices in USD. Nothing can be purchased.'
+ : 'Review your items before checkout.';
+ return (
+
+ {drawer ? (
+ {text}
+ ) : (
+ {text}
+ )}
+
+ );
+}
+
+/** The drawer's close button. Renders nothing outside the drawer. */
+export function CartClose({ className }: CartPartProps): ReactElement | null {
+ useCartInternal('CartClose');
+ if (!useContext(CartDrawerContext)) return null;
+ return (
+
+
+ ✕
+
+
+ );
+}
+
+/** A storage warning, and a cart error with a refresh button. Renders nothing when there are neither. */
+export function CartNotices({ className }: CartPartProps): ReactElement | null {
+ const { storageWarning, error, action, locked, run, refresh } = useCartInternal('CartNotices');
+ if (!storageWarning && !error) return null;
+ // The gap is on an inner element, so host layout classes on the part still apply. (`space-y-*` would lose to the
+ // reset's paragraph margin.)
+ return (
+
+
+ {storageWarning && (
+
+ {storageWarning}
+
+ )}
+ {error && (
+
+ {error}
+
+
+ )}
+
+
+ );
+}
+
+const CartItemsContext = createContext(null);
+const CartItemsRegistry = createContext(null);
+const CartItemContext = createContext(null);
+
+function useCartItemInternal(part: string): CartItemState {
+ const item = useContext(CartItemContext);
+ if (!item) throw new Error(`${part} must be rendered inside .`);
+ return item;
+}
+
+/** Read the line from inside `CartItemRoot`, for custom item parts. */
+export function useCartItem(): CartItemState {
+ return useCartItemInternal('useCartItem');
+}
+
+export interface CartItemsProps extends CartPartProps {
+ /** One item, rendered for every cart line. Defaults to the packaged item. */
+ children?: ReactNode;
+}
+
+/**
+ * The cart lines as a list. `className` goes on the list element whose children are the items. While the saved cart
+ * loads, a status message renders just before it.
+ */
+export function CartItems({ className, children }: CartItemsProps): ReactElement {
+ const { items, hydrating } = useCartInternal('CartItems');
+ // `{custom && …}` with `custom` false still gets an item, not an empty slot per line.
+ const template: ReactNode = hasChildren(children) ? children : packagedItem;
+ const registry = usePartRegistry();
+ const { has } = registry;
+ // Parent effects run after child effects, so every rendered item has registered by now. Development builds only.
+ useEffect(() => {
+ if (process.env.NODE_ENV === 'production' || items.length === 0 || has('item')) return;
+ console.warn(
+ '[gd-commerce-storefront] The template renders no , so the cart list has no items. ' +
+ 'Wrap each line in .',
+ );
+ }, [items.length, has]);
+ return (
+
+ {hydrating && Loading your cart…
}
+ {/* A `` needs a package margin and padding reset, which would beat host classes here. */}
+
+ {items.map((item, index) => (
+
+ {template}
+
+ ))}
+
+
+ );
+}
+
+export interface CartItemRootProps {
+ children: ReactNode;
+ /** Added to the item's list item element. */
+ className?: string;
+}
+
+/** One cart line. Render it as the child of `CartItems`, which renders it once for every line. */
+export function CartItemRoot({ children, className }: CartItemRootProps): ReactElement {
+ const item = useContext(CartItemsContext);
+ const register = useContext(CartItemsRegistry);
+ useEffect(() => register?.('item'), [register]);
+ if (!item) throw new Error('CartItemRoot must be rendered inside .');
+ return (
+
+
+ {/* An item nested inside this one is not a cart line. */}
+ {children}
+
+
+ );
+}
+
+/** The line's product image. Renders nothing without one. */
+export function CartItemImage({ className }: CartPartProps): ReactElement | null {
+ const { imageUrl } = useCartItemInternal('CartItemImage');
+ if (!imageUrl) return null;
+ return (
+
+ 
+
+ );
+}
+
+/** The product name as an H3. */
+export function CartItemName({ className }: CartPartProps): ReactElement {
+ const { name } = useCartItemInternal('CartItemName');
+ return (
+
+ {name}
+
+ );
+}
+
+/** The selected options, one per line, such as "Color: Blue". Renders nothing without options. */
+export function CartItemOptions({ className }: CartPartProps): ReactElement | null {
+ const { options } = useCartItemInternal('CartItemOptions');
+ if (!options.length) return null;
+ return (
+
+ {options.map((option) => (
+
+ {option.attribute}: {option.values.join(', ')}
+
+ ))}
+
+ );
+}
+
+/** The line total. */
+export function CartItemPrice({ className }: CartPartProps): ReactElement {
+ const { subtotal, currency } = useCartItemInternal('CartItemPrice');
+ return (
+
+ {subtotal === null ? 'Price unavailable' : money(subtotal, currency)}
+
+ );
+}
+
+const stepperButtonClass: string =
+ 'min-h-11 min-w-11 rounded-lg bg-white text-neutral-900 focus-visible:outline focus-visible:outline-2 disabled:cursor-not-allowed disabled:bg-neutral-100 disabled:text-neutral-600';
+
+/** Decrease and increase buttons around the line's quantity. */
+export function CartItemQuantity({ className }: CartPartProps): ReactElement {
+ const { id, name, quantity } = useCartItemInternal('CartItemQuantity');
+ const { action, locked, run, changeQuantity } = useCartInternal('CartItemQuantity');
+ return (
+
+
+
+
+ Quantity:
+ {quantity}
+
+
+
+
+ );
+}
+
+/** Removes the line. */
+export function CartItemRemove({ className }: CartPartProps): ReactElement {
+ const { id, name } = useCartItemInternal('CartItemRemove');
+ const { action, locked, run, removeItem } = useCartInternal('CartItemRemove');
+ return (
+
+
+
+ );
+}
+
+const packagedItem: ReactElement = (
+
+
+
+);
+
+export interface CartEmptyProps extends CartPartProps {
+ /** Replaces the default message and link. */
+ children?: ReactNode;
+}
+
+/** Renders only when the cart is empty: a message and a link to the catalog, or its children. */
+export function CartEmpty({ className, children }: CartEmptyProps): ReactElement | null {
+ const { items, hydrating, isSample, catalogPath, close } = useCartInternal('CartEmpty');
+ if (hydrating || items.length) return null;
+ return (
+
+ {hasChildren(children) ? (
+ children
+ ) : (
+ <>
+ Your cart is empty
+
+ {isSample ? 'Add a sample product to try the cart.' : 'Find something you love in the shop.'}
+
+
+ Browse products
+
+
+ )}
+
+ );
+}
+
+export interface CartSummaryProps extends CartPartProps {
+ children: ReactNode;
+}
+
+/** A container for the subtotal and checkout. Renders only when the cart has items. */
+export function CartSummary({ className, children }: CartSummaryProps): ReactElement | null {
+ const { items } = useCartInternal('CartSummary');
+ if (!items.length) return null;
+ return {children};
+}
+
+/** The subtotal, labeled "Sample subtotal" for samples. Renders nothing until the server prices the cart. */
+export function CartSubtotal({ className }: CartPartProps): ReactElement | null {
+ const { items, subtotal, currency, isSample } = useCartInternal('CartSubtotal');
+ if (!items.length || subtotal === null) return null;
+ return (
+
+
+
+
+
+
+ );
+}
+
+/**
+ * "Shipping, taxes, and discounts are calculated at checkout." Has the stable
+ * `commerce-cart-checkout-adjustments-note` class. Renders nothing for samples or an empty cart.
+ */
+export function CartCheckoutNote({ className }: CartPartProps): ReactElement | null {
+ const { items, isSample } = useCartInternal('CartCheckoutNote');
+ if (isSample || !items.length) return null;
+ // The stable class is on the outer element, so hiding it also removes the host's spacing.
+ return (
+
+ Shipping, taxes, and discounts are calculated at checkout.
+
+ );
+}
+
+/**
+ * The checkout button when `checkoutSuccessPath` is set; otherwise a message that checkout is unavailable.
+ * Samples never check out. Renders nothing for an empty cart.
+ */
+export function CartCheckout({ className }: CartPartProps): ReactElement | null {
+ const { items, isSample, checkoutEnabled, checkoutReady, hydrating, action, locked, run, checkout } =
+ useCartInternal('CartCheckout');
+ if (!items.length) return null;
+ let content: ReactElement;
+ if (isSample)
+ content = Example total in USD. Checkout is not set up yet.
;
+ else if (!checkoutEnabled)
+ content = Checkout is not available yet.
;
+ else
+ content = (
+
+ );
+ return {content};
+}
+
+/** The packaged cart drawer. Compose `CartDrawerRoot` and the cart parts for a custom drawer. */
+export function CartDrawer(): ReactElement {
+ return (
+
+
+
+
+
+
+ );
+}
diff --git a/packages/commerce-storefront/src/cart-state.ts b/packages/commerce-storefront/src/cart-state.ts
new file mode 100644
index 00000000..b60bd782
--- /dev/null
+++ b/packages/commerce-storefront/src/cart-state.ts
@@ -0,0 +1,78 @@
+import { useMemo } from 'react';
+import { useCommerce } from './commerce-provider';
+import { useSampleCart } from './sample-cart';
+
+/** One cart line, for custom cart parts. */
+export interface CartItemState {
+ /** Empty when the server returned a line without an ID. Such a line cannot be changed or removed. */
+ readonly id: string;
+ readonly name: string;
+ readonly quantity: number;
+ readonly imageUrl: string | null;
+ readonly options: readonly { readonly attribute: string; readonly values: readonly string[] }[];
+ /** The line total in minor units, or `null` when the server did not price it. */
+ readonly subtotal: number | null;
+ readonly currency: string;
+}
+
+/** Read-only cart contents: the connected store's cart, or the sample cart while no store is connected. */
+export interface CartState {
+ readonly items: readonly CartItemState[];
+ readonly itemCount: number;
+ /** The cart subtotal in minor units, or `null` when the server did not price it. */
+ readonly subtotal: number | null;
+ readonly currency: string;
+ readonly isSample: boolean;
+ /** `true` while the saved cart loads. */
+ readonly loading: boolean;
+}
+
+/** Read the cart from anywhere inside `CommerceProvider`, for example to build a custom cart button. */
+export function useCart(): CartState {
+ const { cart, config, connection, hydrating } = useCommerce();
+ const sample = useSampleCart();
+ const isSample: boolean = connection === 'unbound';
+ const sampleItems = sample.items;
+ return useMemo((): CartState => {
+ // Shared presentation only: sample entries never become draft orders or live mutation inputs.
+ if (isSample)
+ return {
+ items: sampleItems.map((item) => ({
+ id: item.key,
+ name: item.name,
+ quantity: item.quantity,
+ imageUrl: null,
+ options: [],
+ subtotal: item.price * item.quantity,
+ currency: 'USD',
+ })),
+ itemCount: sampleItems.reduce((total, item) => total + item.quantity, 0),
+ subtotal: sampleItems.reduce((sum, item) => sum + item.price * item.quantity, 0),
+ currency: 'USD',
+ isSample,
+ loading: false,
+ };
+ const currency: string = cart?.totals?.total?.currencyCode ?? config.currencyCode;
+ const lines = cart?.lineItems ?? [];
+ const subtotal = cart?.totals?.subTotal?.value;
+ return {
+ items: lines.map((item) => ({
+ id: item.id ?? '',
+ name: item.name ?? '',
+ quantity: item.quantity ?? 0,
+ imageUrl: item.details?.productAssetUrl || null,
+ options: (item.details?.selectedOptions ?? []).map((option) => ({
+ attribute: option.attribute ?? '',
+ values: option.values ?? [],
+ })),
+ subtotal: typeof item.totals?.subTotal?.value === 'number' ? item.totals.subTotal.value : null,
+ currency: item.totals?.subTotal?.currencyCode ?? currency,
+ })),
+ itemCount: lines.reduce((total, item) => total + (item.quantity ?? 0), 0),
+ subtotal: typeof subtotal === 'number' ? subtotal : null,
+ currency: cart?.totals?.subTotal?.currencyCode ?? currency,
+ isSample,
+ loading: hydrating,
+ };
+ }, [cart, config.currencyCode, hydrating, isSample, sampleItems]);
+}
diff --git a/packages/commerce-storefront/src/cart.tsx b/packages/commerce-storefront/src/cart.tsx
index 871ce681..117b6d8c 100644
--- a/packages/commerce-storefront/src/cart.tsx
+++ b/packages/commerce-storefront/src/cart.tsx
@@ -1,12 +1,8 @@
-import * as Dialog from '@radix-ui/react-dialog';
-import { type ReactElement, useState } from 'react';
-import { Link } from 'react-router';
-import { money } from './api';
-import { type CartSummaryTotals, getCartSummaryTotals } from './cart-model';
+import { type ReactElement, useId, useState } from 'react';
+import { useCart } from './cart-state';
import type { SKU } from './catalog-model';
import { getAvailableInventoryQuantity } from './catalog-model';
import { useCommerce } from './commerce-provider';
-import { useSampleCart } from './sample-cart';
import { StorefrontSurface } from './storefront-surface';
export const buttonClass: string =
@@ -15,12 +11,8 @@ export const inputClass: string =
'min-h-11 rounded-lg border border-neutral-400 bg-white px-3 py-2 text-neutral-900 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-neutral-900';
export function CartButton(): ReactElement {
- const { cart, setOpen, open, connection } = useCommerce();
- const sample = useSampleCart();
- const count: number =
- connection === 'unbound'
- ? sample.items.reduce((total, item) => total + item.quantity, 0)
- : (cart?.lineItems?.reduce((total, item) => total + (item.quantity ?? 0), 0) ?? 0);
+ const { setOpen, open, connection } = useCommerce();
+ const { itemCount } = useCart();
return (
);
}
+/** Whether tracked stock is used up. Oversold SKUs report a negative count. */
+export const isSoldOut = (available: number | null): boolean => available !== null && available <= 0;
+
+/** Why `quantity` cannot be added, or `null` when it can. `available` is `null` when stock is not tracked. */
+export function quantityProblem(quantity: number, available: number | null): string | null {
+ if (!Number.isInteger(quantity) || quantity < 1) return 'Enter a whole number of 1 or more.';
+ if (available !== null && available > 0 && quantity > available) return `Only ${available} available.`;
+ return null;
+}
+
export function AddToCartButton({
sku,
name,
@@ -48,16 +50,17 @@ export function AddToCartButton({
}): ReactElement {
const { addItem, pending, hydrating, error, open, connection } = useCommerce();
const [adding, setAdding] = useState(false);
+ const reasonId = useId();
const available: number | null = getAvailableInventoryQuantity(sku);
- const disabled: boolean =
- connection !== 'ready' ||
- !sku.id ||
- adding ||
- hydrating ||
- available === 0 ||
- !Number.isInteger(quantity) ||
- quantity < 1 ||
- (available !== null && quantity > available);
+ const soldOut: boolean = isSoldOut(available);
+ // Sold out needs no description: the button says so.
+ let reason: string | null = null;
+ if (connection === 'unbound') reason = 'Connect a store to add items to the cart.';
+ else if (connection === 'error') reason = 'The store could not be reached.';
+ else if (connection !== 'ready') reason = 'Connecting to the store…';
+ else if (!sku.id) reason = 'This item cannot be added to the cart.';
+ else if (!soldOut) reason = hydrating ? 'Loading your cart…' : quantityProblem(quantity, available);
+ const disabled: boolean = adding || soldOut || reason !== null;
async function handleAdd(): Promise {
if (disabled || pending || !sku.id) return;
setAdding(true);
@@ -75,10 +78,16 @@ export function AddToCartButton({
disabled={disabled}
aria-disabled={disabled || pending}
aria-busy={adding}
+ aria-describedby={reason ? reasonId : undefined}
onClick={() => void handleAdd()}
>
- {available === 0 ? 'Out of stock' : adding ? 'Adding…' : 'Add to cart'}
+ {soldOut ? 'Out of stock' : adding ? 'Adding…' : 'Add to cart'}
+ {reason && (
+
+ {reason}
+
+ )}
{error && !open && (
{error}
@@ -87,263 +96,3 @@ export function AddToCartButton({
);
}
-
-export function CartDrawer(): ReactElement {
- const {
- config,
- connection,
- cart,
- open,
- setOpen,
- restoreFocus,
- pending,
- hydrating,
- error,
- storageWarning,
- changeQuantity: changeLiveQuantity,
- removeItem: removeLiveItem,
- refresh,
- checkout,
- } = useCommerce();
- const sample = useSampleCart();
- const isSample = connection === 'unbound';
- const changeQuantity = isSample ? sample.changeQuantity : changeLiveQuantity;
- const removeItem = isSample ? sample.remove : removeLiveItem;
- const [drawerAction, setDrawerAction] = useState(null);
- const checkingOut: boolean = drawerAction === 'checkout';
- const locked: boolean = pending || hydrating || drawerAction !== null;
- // Shared presentation only: sample entries never become draft orders or live mutation inputs.
- const items = isSample
- ? sample.items.map((item) => ({
- id: item.key,
- name: item.name,
- quantity: item.quantity,
- image: undefined,
- options: undefined,
- subtotal: item.price * item.quantity,
- currency: 'USD',
- }))
- : (cart?.lineItems ?? []).map((item) => ({
- id: item.id,
- name: item.name,
- quantity: item.quantity,
- image: item.details?.productAssetUrl,
- options: item.details?.selectedOptions,
- subtotal: item.totals?.subTotal?.value,
- currency: item.totals?.subTotal?.currencyCode,
- }));
- const summary: CartSummaryTotals = getCartSummaryTotals(cart);
- const currency: string = isSample ? 'USD' : (cart?.totals?.total?.currencyCode ?? config.currencyCode);
- const subtotal = isSample
- ? sample.items.reduce((sum, item) => sum + item.price * item.quantity, 0)
- : summary.subtotal;
- async function handleAction(action: string, operation: () => Promise): Promise {
- if (locked) return;
- setDrawerAction(action);
- try {
- await operation();
- } finally {
- setDrawerAction(null);
- }
- }
- return (
-
-
-
- {
- event.preventDefault();
- restoreFocus();
- }}
- >
-
-
-
- {isSample ? 'Sample cart' : 'Your cart'}
-
-
- {isSample
- ? 'Example products and prices in USD. Nothing can be purchased.'
- : 'Review your items before checkout.'}
-
-
-
- ✕
-
-
-
- {storageWarning && (
-
- {storageWarning}
-
- )}
- {error && (
-
- {error}
-
-
- )}
- {hydrating && Loading your cart…
}
- {!hydrating && !items.length && (
-
- Your cart is empty
-
- {isSample
- ? 'Add a sample product to try the cart.'
- : 'Find something you love in the shop.'}
-
- setOpen(false)}
- >
- Browse products
-
-
- )}
-
- {items.map((item) => (
-
-
- {items.length > 0 && (
-
-
- {(isSample || typeof cart?.totals?.subTotal?.value === 'number') && (
-
-
- )}
-
- {!isSample && (
-
- Shipping, taxes, and discounts are calculated at checkout.
-
- )}
- {isSample ? (
-
- Example total in USD. Checkout is not set up yet.
-
- ) : config.checkoutSuccessPath ? (
-
- ) : (
- Checkout is not available yet.
- )}
-
- )}
-
-
-
-
- );
-}
diff --git a/packages/commerce-storefront/src/catalog.tsx b/packages/commerce-storefront/src/catalog.tsx
index b8a2e744..b6a535de 100644
--- a/packages/commerce-storefront/src/catalog.tsx
+++ b/packages/commerce-storefront/src/catalog.tsx
@@ -1,19 +1,11 @@
import { type UseQueryResult, useQuery } from '@tanstack/react-query';
-import {
- Children,
- createContext,
- type ReactElement,
- type ReactNode,
- useCallback,
- useContext,
- useMemo,
-} from 'react';
+import { createContext, type ReactElement, type ReactNode, useCallback, useContext, useMemo } from 'react';
import { useSearchParams } from 'react-router';
import { message, request } from './api';
import { buttonClass } from './cart';
import type { SKUGroup, SkuGroupsResult } from './catalog-model';
import { useCommerce } from './commerce-provider';
-import { partClass } from './part';
+import { hasChildren, partClass } from './part';
import {
CatalogItemContext,
PackagedCardParts,
@@ -176,13 +168,13 @@ export interface CatalogProductsProps extends CatalogPartProps {
}
/**
- * The product cards. `className` goes on the element that contains the cards, such as a grid. The loading
- * placeholder, the error with its retry, and the empty message render just before that element.
+ * The product cards. `className` goes on the element that contains the cards, such as a grid. While loading, that
+ * element holds placeholder cards. The error with its retry and the empty message render just before it.
*/
export function CatalogProducts({ className, children }: CatalogProductsProps): ReactElement {
const catalog = useCatalogInternal('CatalogProducts');
// `{custom && …}` with `custom` false still gets a card, not an empty slot per product.
- const card: ReactNode = Children.toArray(children).some((child) => child !== '') ? children : packagedCard;
+ const card: ReactNode = hasChildren(children) ? children : packagedCard;
const nodes: SKUGroup[] | null = catalog.source === 'live' ? catalog.nodes : null;
const items = useMemo(
(): { key: string; item: ProductCardItem }[] =>
@@ -194,23 +186,6 @@ export function CatalogProducts({ className, children }: CatalogProductsProps):
const products = catalog.source === 'live' ? catalog.products : null;
return (
<>
- {products?.isPending && (
-
- )}
{products?.isError && (
{message(products.error)}
@@ -225,11 +200,27 @@ export function CatalogProducts({ className, children }: CatalogProductsProps):
)}
{products?.isSuccess && !items.length && No products available.
}
- {items.map(({ key, item }) => (
-
- {card}
-
- ))}
+ {/* Placeholders go inside the host's element, so they follow its grid. */}
+ {products?.isPending
+ ? [0, 1, 2].map((placeholder: number) => (
+
+ ))
+ : items.map(({ key, item }) => (
+
+ {card}
+
+ ))}
);
@@ -267,8 +258,11 @@ export function CatalogPagination({ className }: CatalogPartProps): ReactElement
}
export interface CatalogProps {
+ /** @deprecated Compose `CatalogRoot` with `(null);
+/** Lets a mounted cart drawer register itself, so adds open it only when one exists. Not public. */
+export const CartDrawerRegistry = createContext<(() => () => void) | null>(null);
+
export function useCommerce(): CommerceContextValue {
const context: CommerceContextValue | null = useContext(CommerceContext);
if (!context)
@@ -67,6 +73,19 @@ export interface CommerceProviderProps {
theme?: StorefrontTheme;
/** Set only when your server has enabled checkout and this return route exists. */
checkoutSuccessPath?: string;
+ /**
+ * Called after an item is added, live or sample. With a drawer mounted, the drawer also opens. Without one, such as
+ * on a site with a cart page, use it to confirm the add.
+ */
+ onItemAdded?: (item: AddedCartItem) => void;
+}
+
+/** The item passed to `onItemAdded`. */
+export interface AddedCartItem {
+ readonly name: string;
+ readonly quantity: number;
+ /** `true` for the sample cart, before a store is connected. */
+ readonly isSample: boolean;
}
type PublicConfiguration =
@@ -101,6 +120,7 @@ export function CommerceProvider({
productPath = '/products',
checkoutSuccessPath,
theme = {},
+ onItemAdded,
}: CommerceProviderProps): ReactElement {
const config = useQuery({
retry: false,
@@ -138,6 +158,7 @@ export function CommerceProvider({
void config.refetch();
}}
theme={theme}
+ onItemAdded={onItemAdded}
>
{children}
@@ -151,7 +172,9 @@ function BoundCommerceProvider({
connectionError,
retryConnection,
theme,
+ onItemAdded,
}: {
+ onItemAdded?: (item: AddedCartItem) => void;
connection: CommerceContextValue['connection'];
connectionError: string | null;
retryConnection: () => void;
@@ -180,6 +203,29 @@ function BoundCommerceProvider({
const alive = useRef(true);
const opener = useRef(null);
+ const added = useRef(onItemAdded);
+ added.current = onItemAdded;
+ const drawers = useRef(0);
+ const registerDrawer = useCallback((): (() => void) => {
+ drawers.current += 1;
+ if (process.env.NODE_ENV !== 'production' && drawers.current === 2)
+ console.warn(
+ '[gd-commerce-storefront] More than one cart drawer is mounted, so every add opens all of them. ' +
+ 'CommerceStorefront already mounts CartDrawer; use CommerceProvider to mount your own CartDrawerRoot.',
+ );
+ return () => {
+ drawers.current -= 1;
+ if (drawers.current === 0) setOpen(false);
+ };
+ }, []);
+
+ /** Opens the drawer for an add, if one is mounted. */
+ function openDrawer(): void {
+ if (drawers.current === 0) return;
+ rememberOpener();
+ setOpen(true);
+ }
+
function rememberOpener(): void {
opener.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
}
@@ -324,7 +370,8 @@ function BoundCommerceProvider({
if (!isActive()) return;
commit(result.cart);
setAnnouncement(`${item.name} added to your cart.`);
- setOpen(true);
+ openDrawer();
+ added.current?.({ name: item.name, quantity: item.quantity, isSample: false });
});
}
@@ -412,6 +459,7 @@ function BoundCommerceProvider({
cart,
open,
setOpen: (next) => {
+ if (next && drawers.current === 0) return;
if (next) rememberOpener();
setOpen(next);
},
@@ -431,17 +479,19 @@ function BoundCommerceProvider({
checkout,
}}
>
- {
- rememberOpener();
- setAnnouncement(`${name} added to your sample cart.`);
- setOpen(true);
- }}
- >
- {children}
-
+
+ {
+ setAnnouncement(`${name} added to your sample cart.`);
+ openDrawer();
+ added.current?.({ name, quantity: 1, isSample: true });
+ }}
+ >
+ {children}
+
+
{announcement}
diff --git a/packages/commerce-storefront/src/commerce-storefront.tsx b/packages/commerce-storefront/src/commerce-storefront.tsx
index 00ed0f06..399b59c4 100644
--- a/packages/commerce-storefront/src/commerce-storefront.tsx
+++ b/packages/commerce-storefront/src/commerce-storefront.tsx
@@ -1,4 +1,4 @@
-import { CartDrawer } from './cart';
+import { CartDrawer } from './cart-parts';
import { CommerceProvider, type CommerceProviderProps } from './commerce-provider';
/** Mount once inside the application's Router and QueryClientProvider. */
diff --git a/packages/commerce-storefront/src/index.ts b/packages/commerce-storefront/src/index.ts
index 1d585e67..ea6801c2 100644
--- a/packages/commerce-storefront/src/index.ts
+++ b/packages/commerce-storefront/src/index.ts
@@ -1,7 +1,38 @@
export { ApiError, money, type StorefrontConfig } from './api';
-export { AddToCartButton, CartButton, CartDrawer } from './cart';
+export { AddToCartButton, CartButton } from './cart';
export type * from './cart-model';
export { getCartSummaryTotals } from './cart-model';
+export {
+ CartCheckout,
+ CartCheckoutNote,
+ CartClose,
+ CartDescription,
+ CartDrawer,
+ CartDrawerRoot,
+ type CartDrawerRootProps,
+ CartEmpty,
+ type CartEmptyProps,
+ CartItemImage,
+ CartItemName,
+ CartItemOptions,
+ CartItemPrice,
+ CartItemQuantity,
+ CartItemRemove,
+ CartItemRoot,
+ type CartItemRootProps,
+ CartItems,
+ type CartItemsProps,
+ CartNotices,
+ type CartPartProps,
+ CartRoot,
+ type CartRootProps,
+ CartSubtotal,
+ CartSummary,
+ type CartSummaryProps,
+ CartTitle,
+ useCartItem,
+} from './cart-parts';
+export { type CartItemState, type CartState, useCart } from './cart-state';
export {
Catalog,
CatalogHeader,
@@ -25,6 +56,7 @@ export {
getSingleMatchedSku,
} from './catalog-model';
export {
+ type AddedCartItem,
type CommerceContextValue,
CommerceProvider,
type CommerceProviderProps,
diff --git a/packages/commerce-storefront/src/part.ts b/packages/commerce-storefront/src/part.ts
index a609e14a..c9de6514 100644
--- a/packages/commerce-storefront/src/part.ts
+++ b/packages/commerce-storefront/src/part.ts
@@ -1,4 +1,8 @@
-import { useCallback, useMemo, useRef } from 'react';
+import { Children, type ReactNode, useCallback, useMemo, useRef } from 'react';
+
+/** Whether `children` renders anything, so `{custom && ): string => classes.filter(Boolean).join(' ');
diff --git a/packages/commerce-storefront/src/product-details.test.tsx b/packages/commerce-storefront/src/product-details.test.tsx
index a995d8d6..a56a3a33 100644
--- a/packages/commerce-storefront/src/product-details.test.tsx
+++ b/packages/commerce-storefront/src/product-details.test.tsx
@@ -177,6 +177,33 @@ describe('composable product details', () => {
expect(await screen.findByRole('spinbutton', { name: 'Quantity' })).toHaveValue(1);
});
+ it('explains a quantity that cannot be added, next to the field and on the button', async () => {
+ mockApi(poster);
+ mount(
+
+ ,
+ '/products/poster',
+ );
+ await userEvent.selectOptions(await screen.findByRole('combobox', { name: 'Option' }), 'poster-small');
+ const quantity = await screen.findByRole('spinbutton', { name: 'Quantity' });
+ const add = screen.getByRole('button', { name: 'Add to cart' });
+ await waitFor(() => expect(add).toBeEnabled());
+ expect(quantity).not.toHaveAttribute('aria-invalid');
+ await userEvent.clear(quantity);
+ await userEvent.type(quantity, '4');
+ expect(quantity).toHaveAttribute('aria-invalid', 'true');
+ expect(quantity).toHaveAccessibleDescription('Only 3 available.');
+ expect(screen.getByText('Only 3 available.', { selector: 'p' })).toBeVisible();
+ expect(add).toBeDisabled();
+ expect(add).toHaveAccessibleDescription('Only 3 available.');
+ await userEvent.clear(quantity);
+ expect(quantity).toHaveAccessibleDescription('Enter a whole number of 1 or more.');
+ await userEvent.type(quantity, '2');
+ expect(quantity).not.toHaveAttribute('aria-describedby');
+ expect(add).toBeEnabled();
+ });
+
it('warns when a layout leaves out an option the product needs', async () => {
mockApi();
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
diff --git a/packages/commerce-storefront/src/product-purchase.tsx b/packages/commerce-storefront/src/product-purchase.tsx
index b39b0486..388afd58 100644
--- a/packages/commerce-storefront/src/product-purchase.tsx
+++ b/packages/commerce-storefront/src/product-purchase.tsx
@@ -1,6 +1,6 @@
import { type ComponentProps, type ReactElement, useId } from 'react';
import { message } from './api';
-import { AddToCartButton, buttonClass, inputClass } from './cart';
+import { AddToCartButton, buttonClass, inputClass, isSoldOut, quantityProblem } from './cart';
import type { SKU } from './catalog-model';
import { partClass } from './part';
import {
@@ -189,7 +189,7 @@ export function ProductDetailsAvailability({ className }: ProductDetailsPartProp
{availableQuantity === null
? 'Available to order'
- : availableQuantity === 0
+ : isSoldOut(availableQuantity)
? 'This variant is out of stock'
: `${availableQuantity} available`}
@@ -197,12 +197,17 @@ export function ProductDetailsAvailability({ className }: ProductDetailsPartProp
);
}
-/** Quantity for the verified SKU. Renders nothing until a SKU is verified. */
+/** Quantity for the verified SKU, with a message when it cannot be added. Renders nothing until a SKU is verified. */
export function ProductDetailsQuantity({ className }: ProductDetailsPartProps): ReactElement | null {
const { selectedSku, availableQuantity, quantity, setQuantity } =
useProductDetailsInternal('ProductDetailsQuantity');
const id = useId();
+ const problemId = useId();
if (!selectedSku) return null;
+ // A sold-out SKU has no quantity to fix; its availability and button say so.
+ const problem: string | null = isSoldOut(availableQuantity)
+ ? null
+ : quantityProblem(quantity, availableQuantity);
return (
);
}
diff --git a/packages/commerce-storefront/src/sample-cart.tsx b/packages/commerce-storefront/src/sample-cart.tsx
index 26abb8ce..6a945df4 100644
--- a/packages/commerce-storefront/src/sample-cart.tsx
+++ b/packages/commerce-storefront/src/sample-cart.tsx
@@ -24,6 +24,8 @@ interface SampleCartValue {
remove: (key: string) => Promise;
}
+const noQuantities: Record = {};
+
const SampleCartContext = createContext(null);
export function useSampleCart(): SampleCartValue {
@@ -54,7 +56,15 @@ export function SampleCartProvider({
active.current = null;
};
}, [session]);
- const quantities = state.session === session && enabled ? state.quantities : {};
+ const quantities = state.session === session && enabled ? state.quantities : noQuantities;
+ // Stable while the quantities are, so `useCart` and the cart parts don't recompute on every render.
+ const items = useMemo(
+ () =>
+ sampleProducts.flatMap((product) =>
+ quantities[product.key] ? [{ ...product, quantity: quantities[product.key] }] : [],
+ ),
+ [quantities],
+ );
function update(key: string, quantity?: number): boolean {
if (!enabled || active.current !== session || !sampleProducts.some((product) => product.key === key))
return false;
@@ -71,9 +81,7 @@ export function SampleCartProvider({
return (
- quantities[product.key] ? [{ ...product, quantity: quantities[product.key] }] : [],
- ),
+ items,
add: (key) => {
const product = sampleProducts.find((product) => product.key === key);
if (!product || !update(key)) return false;
diff --git a/packages/commerce-storefront/src/storefront.test.tsx b/packages/commerce-storefront/src/storefront.test.tsx
index ea792253..f7eec8f2 100644
--- a/packages/commerce-storefront/src/storefront.test.tsx
+++ b/packages/commerce-storefront/src/storefront.test.tsx
@@ -129,9 +129,10 @@ describe('shared cart', () => {
act(() => view.context().setOpen(true));
expect(screen.getByText('Subtotal')).toBeVisible();
expect(screen.getByText('$12.00')).toBeVisible();
- expect(screen.getByText('Shipping, taxes, and discounts are calculated at checkout.')).toHaveClass(
- 'commerce-cart-checkout-adjustments-note',
- );
+ // The stable class is on the part's outer element, so hiding it also removes its spacing.
+ const note = screen.getByText('Shipping, taxes, and discounts are calculated at checkout.');
+ expect(note).not.toHaveClass('commerce-cart-checkout-adjustments-note');
+ expect(note.parentElement).toHaveClass('commerce-cart-checkout-adjustments-note');
expect(screen.queryByText('Total')).not.toBeInTheDocument();
expect(screen.queryByText('$1.00')).not.toBeInTheDocument();
});
Cart
+Nothing here yet.
+Custom
}line
+{text}
+ )} ++ {storageWarning} +
+ )} + {error && ( +{error}
+ +Loading your cart…
} + {/* A `- ` needs a package margin and padding reset, which would beat host classes here. */}
+
{name}
++ {option.attribute}: {option.values.join(', ')} +
+ ))} +{subtotal === null ? 'Price unavailable' : money(subtotal, currency)}
+Your cart is empty
++ {isSample ? 'Add a sample product to try the cart.' : 'Find something you love in the shop.'} +
+ + Browse products + + + )} +-
+
Shipping, taxes, and discounts are calculated at checkout.
+Example total in USD. Checkout is not set up yet.
; + else if (!checkoutEnabled) + content =Checkout is not available yet.
; + else + content = ( + + ); + return
{error}
@@ -87,263 +96,3 @@ export function AddToCartButton({
);
}
-
-export function CartDrawer(): ReactElement {
- const {
- config,
- connection,
- cart,
- open,
- setOpen,
- restoreFocus,
- pending,
- hydrating,
- error,
- storageWarning,
- changeQuantity: changeLiveQuantity,
- removeItem: removeLiveItem,
- refresh,
- checkout,
- } = useCommerce();
- const sample = useSampleCart();
- const isSample = connection === 'unbound';
- const changeQuantity = isSample ? sample.changeQuantity : changeLiveQuantity;
- const removeItem = isSample ? sample.remove : removeLiveItem;
- const [drawerAction, setDrawerAction] = useState
- {storageWarning}
- {error} Loading your cart… Your cart is empty
- {isSample
- ? 'Add a sample product to try the cart.'
- : 'Find something you love in the shop.'}
-
- Shipping, taxes, and discounts are calculated at checkout.
-
- Example total in USD. Checkout is not set up yet.
- Checkout is not available yet. {message(products.error)} No products available.
{availableQuantity === null
? 'Available to order'
- : availableQuantity === 0
+ : isSoldOut(availableQuantity)
? 'This variant is out of stock'
: `${availableQuantity} available`}
- {items.map((item) => (
-
-
- {(isSample || typeof cart?.totals?.subTotal?.value === 'number') && (
-
- {!isSample && (
-