@webround/commerce-react 0.0.0-stage → 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { useResource } from './use-resource.js';
+export type { UseResourceOptions, UseResourceResult } from './use-resource.js';
+export { useShop } from './use-shop.js';
+export type { UseShopOptions, UseShopResult } from './use-shop.js';
+export { useShopAddress } from './use-shop-address.js';
+export type { UseShopAddressOptions } from './use-shop-address.js';
+export { authActions, useAuth } from './use-auth.js';
+export type { AuthActions, UseAuthResult } from './use-auth.js';
+export { cartActions, useCart } from './use-cart.js';
+export type { CartActions, UseCartResult } from './use-cart.js';
+export { useAccount } from './use-account.js';
+export type { UseAccountResult } from './use-account.js';
+export { checkoutActions, useCheckout } from './use-checkout.js';
+export type { CheckoutActions, UseCheckoutOptions, UseCheckoutResult } from './use-checkout.js';
+export { addressActions, useAddresses } from './use-addresses.js';
+export type { AddressActions, UseAddressesResult } from './use-addresses.js';
+export { useCustomerResource } from './use-customer-resource.js';
+export { useOrder, useOrders, useSubscription, useSubscriptions } from './use-orders.js';
+export { useGuestReturnSession, useReturnRequest, useReturnRequests } from './use-returns.js';
+export { useWishlist } from './use-wishlist.js';
+export type { UseWishlistResult } from './use-wishlist.js';
+export { useMyReviews, useReviewAbility } from './use-reviews.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,15 @@
+// @webround/commerce-react: what a React component needs to use a store (React 19). The logic is `@webround/commerce`'s; this only binds it to components.
+export { useResource } from './use-resource.js';
+export { useShop } from './use-shop.js';
+export { useShopAddress } from './use-shop-address.js';
+export { authActions, useAuth } from './use-auth.js';
+export { cartActions, useCart } from './use-cart.js';
+export { useAccount } from './use-account.js';
+export { checkoutActions, useCheckout } from './use-checkout.js';
+export { addressActions, useAddresses } from './use-addresses.js';
+export { useCustomerResource } from './use-customer-resource.js';
+export { useOrder, useOrders, useSubscription, useSubscriptions } from './use-orders.js';
+export { useGuestReturnSession, useReturnRequest, useReturnRequests } from './use-returns.js';
+export { useWishlist } from './use-wishlist.js';
+export { useMyReviews, useReviewAbility } from './use-reviews.js';
+//# sourceMappingURL=index.js.map

package/dist/site.d.ts

@@ -0,0 +1,7 @@
+import { type WrSiteEnv } from '@webround/core/site-env';
+import { type Commerce, type CommerceConfig } from '@webround/commerce';
+/** The store `env` describes. Throws, naming what is missing, when it does not say enough. */
+export declare function commerceFromEnv(env: WrSiteEnv, options?: Omit<CommerceConfig, 'storeId' | 'commerceApiUrl' | 'catalogApiUrl' | 'checkoutApiUrl'>): Commerce;
+/** This site's store: its session, its catalog, its cache. Made the first time one of them is read. */
+export declare const commerce: Commerce;
+//# sourceMappingURL=site.d.ts.map

package/dist/site.js

@@ -0,0 +1,41 @@
+import { wrSiteEnv, WR_SITE_ENV_VARS } from '@webround/core/site-env';
+import { createCommerce } from '@webround/commerce';
+// `@webround/commerce-react/site`: the store of THIS site, made from what the site was built with (`VITE_WR_*`, set by the Worker that runs the draft; `wrSiteEnv` of @webround/core is the one place that reads them).
+//
+//   import { commerce } from '@webround/commerce-react/site';
+//   const { actions } = useAuth(commerce.auth);
+//
+// Nothing is made until it is used: a page that never touches the store costs nothing, and a site built without the variables fails WHERE it uses the store, saying which one is missing, not when it loads.
+/** The store `env` describes. Throws, naming what is missing, when it does not say enough. */
+export function commerceFromEnv(env, options = {}) {
+    const { draftId, commerceApiUrl, catalogApiUrl, checkoutApiUrl } = env;
+    if (draftId === undefined || commerceApiUrl === undefined || catalogApiUrl === undefined) {
+        const missing = [
+            draftId === undefined ? WR_SITE_ENV_VARS.draftId : null,
+            commerceApiUrl === undefined ? WR_SITE_ENV_VARS.commerceApiUrl : null,
+            catalogApiUrl === undefined ? WR_SITE_ENV_VARS.catalogApiUrl : null,
+        ].filter((name) => name !== null);
+        throw new Error(`@webround/commerce: this site was built without ${missing.join(', ')}, so it does not know which store to talk to.`);
+    }
+    // The checkout's address is not needed to run the store: a site without it fails where it uses the checkout, saying so
+    return createCommerce({ ...options, storeId: draftId, commerceApiUrl, catalogApiUrl, ...(checkoutApiUrl !== undefined ? { checkoutApiUrl } : {}) });
+}
+let made;
+// This site prices and describes its cart with the checkout's preview (`commerce.checkout`): `/cart/total` is never asked
+const store = () => (made ?? (made = commerceFromEnv(wrSiteEnv(), { cartPricing: false })));
+/** This site's store: its session, its catalog, its cache. Made the first time one of them is read. */
+export const commerce = {
+    get storeId() { return store().storeId; },
+    get auth() { return store().auth; },
+    get catalog() { return store().catalog; },
+    get cache() { return store().cache; },
+    get cart() { return store().cart; },
+    get checkout() { return store().checkout; },
+    get account() { return store().account; },
+    get addresses() { return store().addresses; },
+    get orders() { return store().orders; },
+    get returns() { return store().returns; },
+    get wishlist() { return store().wishlist; },
+    get reviews() { return store().reviews; },
+};
+//# sourceMappingURL=site.js.map

package/dist/use-account.d.ts

@@ -0,0 +1,12 @@
+import { type Account, type NewsletterStrategy } from '@webround/commerce';
+import type { Auth } from '@webround/commerce';
+export interface UseAccountResult {
+    /** What subscribing to, or cancelling, the newsletter will do now. */
+    newsletter: NewsletterStrategy;
+    actions: Account;
+}
+export declare function useAccount(commerce: {
+    account: Account;
+    auth: Pick<Auth, 'store'>;
+}): UseAccountResult;
+//# sourceMappingURL=use-account.d.ts.map

package/dist/use-account.js

@@ -0,0 +1,9 @@
+import { useMemo, useSyncExternalStore } from 'react';
+import { newsletterStrategy } from '@webround/commerce';
+export function useAccount(commerce) {
+    const { store } = commerce.auth;
+    const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+    const newsletter = useMemo(() => newsletterStrategy(state), [state.status, state.customer?.email, state.customer?.emailVerified]);
+    return { newsletter, actions: commerce.account };
+}
+//# sourceMappingURL=use-account.js.map

package/dist/use-addresses.d.ts

@@ -0,0 +1,20 @@
+import type { AddressBook, AddressBookState } from '@webround/commerce';
+export interface AddressActions {
+    save: AddressBook['save'];
+    remember: AddressBook['remember'];
+    update: AddressBook['update'];
+    remove: AddressBook['remove'];
+    setDefault: AddressBook['setDefault'];
+    refresh: AddressBook['refresh'];
+}
+export interface UseAddressesResult {
+    state: AddressBookState;
+    addresses: AddressBookState['addresses'];
+    actions: AddressActions;
+}
+export declare function addressActions(book: AddressBook): AddressActions;
+/** `commerce` is what `createCommerce` made (or `@webround/commerce-react/site`'s). Any number of components can use it: the book starts once. A server render says `unknown` and no addresses. */
+export declare function useAddresses(commerce: {
+    addresses: AddressBook;
+}): UseAddressesResult;
+//# sourceMappingURL=use-addresses.d.ts.map

package/dist/use-addresses.js

@@ -0,0 +1,20 @@
+import { useEffect, useMemo, useSyncExternalStore } from 'react';
+export function addressActions(book) {
+    return {
+        save: (input) => book.save(input),
+        remember: (input) => book.remember(input),
+        update: (id, patch) => book.update(id, patch),
+        remove: (id) => book.remove(id),
+        setDefault: (id, kind) => book.setDefault(id, kind),
+        refresh: () => book.refresh(),
+    };
+}
+/** `commerce` is what `createCommerce` made (or `@webround/commerce-react/site`'s). Any number of components can use it: the book starts once. A server render says `unknown` and no addresses. */
+export function useAddresses(commerce) {
+    const { addresses: book } = commerce;
+    const state = useSyncExternalStore(book.subscribe, book.getState, book.getState);
+    const actions = useMemo(() => addressActions(book), [book]);
+    useEffect(() => { void book.start(); }, [book]);
+    return { state, addresses: state.addresses, actions };
+}
+//# sourceMappingURL=use-addresses.js.map

package/dist/use-auth.d.ts

@@ -0,0 +1,24 @@
+import type { Auth } from '@webround/commerce';
+import type { AuthState, AuthStatus, AuthStore, Customer } from '@webround/commerce';
+import type { TwoFactorChallenge } from '@webround/commerce';
+/** What changes the session. A call that fails THROWS what the store said (a wrong password, a validation list in `issues`): it belongs to the form that made it. */
+export interface AuthActions {
+    signup: AuthStore['signup'];
+    login: AuthStore['login'];
+    verifyTwoFactor: AuthStore['verifyTwoFactor'];
+    cancelChallenge: AuthStore['cancelChallenge'];
+    logout: AuthStore['logout'];
+}
+export interface UseAuthResult {
+    state: AuthState;
+    /** `unknown` until it is known whether a customer is kept (and on a server render: no window, nobody to take back). */
+    status: AuthStatus;
+    customer: Customer | null;
+    /** The code of the authenticator app is wanted (status `challenge`). */
+    challenge: TwoFactorChallenge | null;
+    actions: AuthActions;
+}
+export declare function authActions(store: AuthStore): AuthActions;
+/** `auth` is what `createAuth` made. Any number of components can use it: the customer is taken back once. */
+export declare function useAuth(auth: Pick<Auth, 'store'>): UseAuthResult;
+//# sourceMappingURL=use-auth.d.ts.map

package/dist/use-auth.js

@@ -0,0 +1,20 @@
+import { useEffect, useMemo, useSyncExternalStore } from 'react';
+export function authActions(store) {
+    return {
+        signup: (input, options) => store.signup(input, options),
+        login: (input) => store.login(input),
+        verifyTwoFactor: (code) => store.verifyTwoFactor(code),
+        cancelChallenge: () => store.cancelChallenge(),
+        logout: () => store.logout(),
+    };
+}
+/** `auth` is what `createAuth` made. Any number of components can use it: the customer is taken back once. */
+export function useAuth(auth) {
+    const { store } = auth;
+    const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+    const actions = useMemo(() => authActions(store), [store]);
+    // Not in render: a server render asks nothing. `restore` is one call for whoever asks while it is under way, and nothing once it is known
+    useEffect(() => { void store.restore(); }, [store]);
+    return { state, status: state.status, customer: state.customer, challenge: state.challenge, actions };
+}
+//# sourceMappingURL=use-auth.js.map

package/dist/use-cart.d.ts

@@ -0,0 +1,27 @@
+import type { CartState, CartStore } from '@webround/commerce';
+export interface CartActions {
+    add: CartStore['add'];
+    setQuantity: CartStore['setQuantity'];
+    remove: CartStore['remove'];
+    /** Empties the cart (a guest's and a customer's). */
+    clear: CartStore['clear'];
+    refresh: CartStore['refresh'];
+}
+export interface UseCartResult {
+    state: CartState;
+    /** How many items are in the cart: known before the store has priced anything. */
+    count: number;
+    /** What the store says the cart costs (null until it said); `state.isStale` when it is one change behind. */
+    priced: CartState['priced'];
+    actions: CartActions;
+}
+export declare function cartActions(store: CartStore): CartActions;
+/**
+ * To step a quantity (a "+" button), read it from `state.lines`, not from `priced`: `lines` is what the cart is NOW (a change shows in it at once), `priced` is the store's answer, which can be one change behind
+ * (`state.isStale`), so three quick clicks on a "+" that reads `priced` ask for the same quantity three times.
+ */
+/** `commerce` is what `createCommerce` made (or `@webround/commerce-react/site`'s). Any number of components can use it: the cart starts once. A server render says `unknown` and zero items, as the first render in the browser does. */
+export declare function useCart(commerce: {
+    cart: CartStore;
+}): UseCartResult;
+//# sourceMappingURL=use-cart.d.ts.map

package/dist/use-cart.js

@@ -0,0 +1,23 @@
+import { useEffect, useMemo, useSyncExternalStore } from 'react';
+export function cartActions(store) {
+    return {
+        add: (line) => store.add(line),
+        setQuantity: (variantId, quantity) => store.setQuantity(variantId, quantity),
+        remove: (variantId) => store.remove(variantId),
+        clear: () => store.clear(),
+        refresh: () => store.refresh(),
+    };
+}
+/**
+ * To step a quantity (a "+" button), read it from `state.lines`, not from `priced`: `lines` is what the cart is NOW (a change shows in it at once), `priced` is the store's answer, which can be one change behind
+ * (`state.isStale`), so three quick clicks on a "+" that reads `priced` ask for the same quantity three times.
+ */
+/** `commerce` is what `createCommerce` made (or `@webround/commerce-react/site`'s). Any number of components can use it: the cart starts once. A server render says `unknown` and zero items, as the first render in the browser does. */
+export function useCart(commerce) {
+    const { cart } = commerce;
+    const state = useSyncExternalStore(cart.subscribe, cart.getState, cart.getState);
+    const actions = useMemo(() => cartActions(cart), [cart]);
+    useEffect(() => { void cart.start(); }, [cart]);
+    return { state, count: state.count, priced: state.priced, actions };
+}
+//# sourceMappingURL=use-cart.js.map

package/dist/use-checkout.d.ts

@@ -0,0 +1,37 @@
+import type { CheckoutState, CheckoutStore } from '@webround/commerce';
+export interface CheckoutActions {
+    setDeliveryMethod: CheckoutStore['setDeliveryMethod'];
+    setShippingAddress: CheckoutStore['setShippingAddress'];
+    setBillingAddress: CheckoutStore['setBillingAddress'];
+    selectShippingMethod: CheckoutStore['selectShippingMethod'];
+    setPromotionCodes: CheckoutStore['setPromotionCodes'];
+    setAdditionalData: CheckoutStore['setAdditionalData'];
+    setEmail: CheckoutStore['setEmail'];
+    setInvoice: CheckoutStore['setInvoice'];
+    /** Asks the preview now (what it asked automatically is asked again). Throws what the store refuses. */
+    quote: CheckoutStore['quote'];
+    /** Starts the payment; give the customer the `url` it answers (`location.assign(url)`). Throws what the store refuses. */
+    pay: CheckoutStore['pay'];
+    reset: CheckoutStore['reset'];
+    /** The payment is done (the success page): empties the cart and forgets the checkout. */
+    complete: CheckoutStore['complete'];
+}
+export interface UseCheckoutOptions {
+    /**
+     * Ask the preview by itself when the cart or what the customer chose changes (default: yes). Not for an empty cart, and not again for what already failed (ask again with `actions.quote`). A refusal is not thrown
+     * here: it is in `state.error`.
+     */
+    autoQuote?: boolean;
+}
+export interface UseCheckoutResult {
+    state: CheckoutState;
+    /** What the store says it costs (null until it said); `state.isStale` when it is the answer to something the customer has since changed. */
+    quote: CheckoutState['quote'];
+    actions: CheckoutActions;
+}
+export declare function checkoutActions(store: CheckoutStore): CheckoutActions;
+/** `commerce` is what `createCommerce` made (or `@webround/commerce-react/site`'s). Reading `commerce.checkout` needs the checkout API's address. */
+export declare function useCheckout(commerce: {
+    checkout: CheckoutStore;
+}, options?: UseCheckoutOptions): UseCheckoutResult;
+//# sourceMappingURL=use-checkout.d.ts.map

package/dist/use-checkout.js

@@ -0,0 +1,33 @@
+import { useEffect, useMemo, useSyncExternalStore } from 'react';
+export function checkoutActions(store) {
+    return {
+        setDeliveryMethod: (variantId, method) => store.setDeliveryMethod(variantId, method),
+        setShippingAddress: (address) => store.setShippingAddress(address),
+        setBillingAddress: (address) => store.setBillingAddress(address),
+        selectShippingMethod: (id) => store.selectShippingMethod(id),
+        setPromotionCodes: (codes) => store.setPromotionCodes(codes),
+        setAdditionalData: (data) => store.setAdditionalData(data),
+        setEmail: (email) => store.setEmail(email),
+        setInvoice: (invoice) => store.setInvoice(invoice),
+        quote: (options) => store.quote(options),
+        pay: (returnUrls) => store.pay(returnUrls),
+        reset: () => store.reset(),
+        complete: () => store.complete(),
+    };
+}
+/** `commerce` is what `createCommerce` made (or `@webround/commerce-react/site`'s). Reading `commerce.checkout` needs the checkout API's address. */
+export function useCheckout(commerce, options = {}) {
+    const { checkout } = commerce;
+    const autoQuote = options.autoQuote ?? true;
+    const state = useSyncExternalStore(checkout.subscribe, checkout.getState, checkout.getState);
+    const actions = useMemo(() => checkoutActions(checkout), [checkout]);
+    useEffect(() => { checkout.start(); }, [checkout]);
+    // Which questions were asked is the store's to remember (one for all the components): a refusal is not asked again by itself, and the same question is never asked twice
+    useEffect(() => {
+        if (!autoQuote)
+            return;
+        checkout.ensureQuote().catch(() => { });
+    }, [checkout, autoQuote, state.requestKey, state.lineCount]);
+    return { state, quote: state.quote, actions };
+}
+//# sourceMappingURL=use-checkout.js.map

package/dist/use-customer-resource.d.ts

@@ -0,0 +1,5 @@
+import type { Auth } from '@webround/commerce';
+import type { Resource } from '@webround/commerce';
+import { type UseResourceOptions, type UseResourceResult } from './use-resource.js';
+export declare function useCustomerResource<T>(auth: Pick<Auth, 'store'>, make: () => Resource<T> | null, options?: UseResourceOptions): UseResourceResult<T>;
+//# sourceMappingURL=use-customer-resource.d.ts.map

package/dist/use-customer-resource.js

@@ -0,0 +1,9 @@
+import { useSyncExternalStore } from 'react';
+import { useResource } from './use-resource.js';
+// A resource that is about the logged-in customer, shown by a component: the same as `useResource`, plus that the component follows who is logged in. Nobody logged in is no resource (`idle`), and logging in or out draws
+// the component again with the right one (the cache forgets what was the customer's when they go).
+export function useCustomerResource(auth, make, options) {
+    useSyncExternalStore(auth.store.subscribe, auth.store.getState, auth.store.getState);
+    return useResource(make(), options);
+}
+//# sourceMappingURL=use-customer-resource.js.map

package/dist/use-orders.d.ts

@@ -0,0 +1,14 @@
+import type { Auth } from '@webround/commerce';
+import type { Orders } from '@webround/commerce';
+import type { Order, OrderPage, PageQuery, Subscription, SubscriptionPage } from '@webround/commerce';
+import type { UseResourceOptions, UseResourceResult } from './use-resource.js';
+type Source = {
+    auth: Pick<Auth, 'store'>;
+    orders: Orders;
+};
+export declare const useOrders: (commerce: Source, query?: PageQuery, options?: UseResourceOptions) => UseResourceResult<OrderPage>;
+export declare const useOrder: (commerce: Source, id: string | null | undefined) => UseResourceResult<Order>;
+export declare const useSubscriptions: (commerce: Source, query?: PageQuery, options?: UseResourceOptions) => UseResourceResult<SubscriptionPage>;
+export declare const useSubscription: (commerce: Source, id: string | null | undefined) => UseResourceResult<Subscription>;
+export {};
+//# sourceMappingURL=use-orders.d.ts.map

package/dist/use-orders.js

@@ -0,0 +1,6 @@
+import { useCustomerResource } from './use-customer-resource.js';
+export const useOrders = (commerce, query, options = { keepPrevious: true }) => useCustomerResource(commerce.auth, () => commerce.orders.list(query), options);
+export const useOrder = (commerce, id) => useCustomerResource(commerce.auth, () => (id ? commerce.orders.get(id) : null));
+export const useSubscriptions = (commerce, query, options = { keepPrevious: true }) => useCustomerResource(commerce.auth, () => commerce.orders.subscriptions.list(query), options);
+export const useSubscription = (commerce, id) => useCustomerResource(commerce.auth, () => (id ? commerce.orders.subscriptions.get(id) : null));
+//# sourceMappingURL=use-orders.js.map

package/dist/use-resource.d.ts

@@ -0,0 +1,25 @@
+import type { Resource } from '@webround/commerce';
+export interface UseResourceOptions {
+    /**
+     * When the question changes (another page of the results, another search), keep showing the answer of the one before until the new one comes, instead of nothing: `data` is that
+     * answer and `isStale` says it is not the one asked for. Off by default: what is shown is always the answer to what is asked.
+     */
+    keepPrevious?: boolean;
+}
+export interface UseResourceResult<T> {
+    /** `idle`: nothing is asked (no resource was given). `pending`: the answer is being waited for. `ready`: it is there. `error`: it could not be had. */
+    status: 'idle' | 'pending' | 'ready' | 'error';
+    /** The answer to what is asked, or (with `keepPrevious`, while the new one is awaited) the answer to the question before; undefined when there is none. */
+    data: T | undefined;
+    /** Why it failed (a `CommerceError` for what the store did, or a network error): set with `status: 'error'`, undefined otherwise. */
+    error: unknown;
+    /** The answer to what is asked is being waited for. */
+    isFetching: boolean;
+    /** `data` is the answer to an earlier question (`keepPrevious`), not to the one asked now. */
+    isStale: boolean;
+    /** Asks again after an error. It does nothing in any other state: what is there is not asked for again (to forget it, invalidate it in the catalog). */
+    retry: () => void;
+}
+/** A resource asked for by a component: `null`/`undefined` is "not asked yet" (a slug that is not known, a search that is not made). */
+export declare function useResource<T>(resource: Resource<T> | null | undefined, options?: UseResourceOptions): UseResourceResult<T>;
+//# sourceMappingURL=use-resource.d.ts.map

package/dist/use-resource.js

@@ -0,0 +1,60 @@
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+const NOTHING = { status: 'idle' };
+const noSubscription = () => () => undefined;
+/** A resource asked for by a component: `null`/`undefined` is "not asked yet" (a slug that is not known, a search that is not made). */
+export function useResource(resource, options = {}) {
+    const keepPrevious = options.keepPrevious === true;
+    const key = resource?.key;
+    // A resource is made again at every render, and the same key is the same question: only a new key is a new one (what is subscribed to must not change on every render)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const asked = useMemo(() => resource ?? null, [key]);
+    const subscribe = useCallback((listener) => (asked ? asked.subscribe(listener) : noSubscription()), [asked]);
+    const read = useCallback(() => (asked ? asked.snapshot() : NOTHING), [asked]);
+    // The server has the same state as the client: what the cache holds when it renders (a prerender fills it before)
+    const snapshot = useSyncExternalStore(subscribe, read, read);
+    // Asks when the question is there, and gives it up when it is gone: a question nobody waits for any more is not asked (the cache sees to that)
+    const waiting = useRef(null);
+    useEffect(() => {
+        if (!asked)
+            return;
+        const controller = (waiting.current = new AbortController());
+        if (asked.snapshot().status !== 'ready')
+            asked.load({ signal: controller.signal }).catch(() => undefined); // the failure is the state of the key, read above
+        return () => { controller.abort(); if (waiting.current === controller)
+            waiting.current = null; };
+    }, [asked]);
+    // What is watched was forgotten (it was invalidated in the catalog): it is asked again, so that what is on the screen is never "nothing" for good
+    const forgotten = asked !== null && snapshot.status === 'idle';
+    useEffect(() => {
+        if (forgotten && waiting.current && asked && asked.snapshot().status === 'idle')
+            asked.load({ signal: waiting.current.signal }).catch(() => undefined);
+    }, [forgotten, asked]);
+    const retrying = useRef(null);
+    useEffect(() => () => { retrying.current?.abort(); retrying.current = null; }, [asked]);
+    const retry = useCallback(() => {
+        if (!asked || asked.snapshot().status !== 'error')
+            return;
+        retrying.current?.abort();
+        const controller = (retrying.current = new AbortController());
+        asked.load({ signal: controller.signal }).catch(() => undefined);
+    }, [asked]);
+    // The last answer that was shown, for `keepPrevious`: kept once it is on the screen
+    const shown = useRef(undefined);
+    const hasShown = useRef(false);
+    useEffect(() => {
+        if (snapshot.status === 'ready') {
+            shown.current = snapshot.data;
+            hasShown.current = true;
+        }
+    }, [snapshot]);
+    if (!asked)
+        return { status: 'idle', data: undefined, error: undefined, isFetching: false, isStale: false, retry };
+    if (snapshot.status === 'ready')
+        return { status: 'ready', data: snapshot.data, error: undefined, isFetching: false, isStale: false, retry };
+    if (snapshot.status === 'error')
+        return { status: 'error', data: undefined, error: snapshot.error, isFetching: false, isStale: false, retry };
+    // `idle` here is a question that is about to be asked (the effect has not run yet): it is awaited, there is no frame in which it is "nothing"
+    const stale = keepPrevious && hasShown.current;
+    return { status: 'pending', data: stale ? shown.current : undefined, error: undefined, isFetching: true, isStale: stale, retry };
+}
+//# sourceMappingURL=use-resource.js.map

package/dist/use-returns.d.ts

@@ -0,0 +1,14 @@
+import type { Auth } from '@webround/commerce';
+import type { Returns } from '@webround/commerce';
+import type { GuestReturnSession, PageQuery, ReturnRequest, ReturnRequestPage } from '@webround/commerce';
+import { type UseResourceOptions, type UseResourceResult } from './use-resource.js';
+type Source = {
+    auth: Pick<Auth, 'store'>;
+    returns: Returns;
+};
+export declare const useReturnRequests: (commerce: Source, query?: PageQuery, options?: UseResourceOptions) => UseResourceResult<ReturnRequestPage>;
+export declare const useReturnRequest: (commerce: Source, id: string | null | undefined) => UseResourceResult<ReturnRequest>;
+/** The order a guest's link opens (the `token` of the page's address; none yet is no question). */
+export declare const useGuestReturnSession: (commerce: Pick<Source, "returns">, token: string | null | undefined) => UseResourceResult<GuestReturnSession>;
+export {};
+//# sourceMappingURL=use-returns.d.ts.map

package/dist/use-returns.js

@@ -0,0 +1,7 @@
+import { useCustomerResource } from './use-customer-resource.js';
+import { useResource } from './use-resource.js';
+export const useReturnRequests = (commerce, query, options = { keepPrevious: true }) => useCustomerResource(commerce.auth, () => commerce.returns.list(query), options);
+export const useReturnRequest = (commerce, id) => useCustomerResource(commerce.auth, () => (id ? commerce.returns.get(id) : null));
+/** The order a guest's link opens (the `token` of the page's address; none yet is no question). */
+export const useGuestReturnSession = (commerce, token) => useResource(token ? commerce.returns.guest.session(token) : null);
+//# sourceMappingURL=use-returns.js.map

package/dist/use-reviews.d.ts

@@ -0,0 +1,14 @@
+import type { Auth } from '@webround/commerce';
+import { type ReviewAbility } from '@webround/commerce';
+import type { Reviews } from '@webround/commerce';
+import type { MyReviewPage, MyReviewsQuery } from '@webround/commerce';
+import type { UseResourceOptions, UseResourceResult } from './use-resource.js';
+type Source = {
+    auth: Pick<Auth, 'store'>;
+    reviews: Reviews;
+};
+export declare const useMyReviews: (commerce: Source, query?: MyReviewsQuery, options?: UseResourceOptions) => UseResourceResult<MyReviewPage>;
+/** Who can write a review now: a guest has to log in, a customer whose address is not verified has to verify it, one whose is can. It follows the session. */
+export declare function useReviewAbility(commerce: Pick<Source, 'auth'>): ReviewAbility;
+export {};
+//# sourceMappingURL=use-reviews.d.ts.map

package/dist/use-reviews.js

@@ -0,0 +1,10 @@
+import { useSyncExternalStore } from 'react';
+import { reviewAbility } from '@webround/commerce';
+import { useCustomerResource } from './use-customer-resource.js';
+export const useMyReviews = (commerce, query, options = { keepPrevious: true }) => useCustomerResource(commerce.auth, () => commerce.reviews.mine(query), options);
+/** Who can write a review now: a guest has to log in, a customer whose address is not verified has to verify it, one whose is can. It follows the session. */
+export function useReviewAbility(commerce) {
+    const state = useSyncExternalStore(commerce.auth.store.subscribe, commerce.auth.store.getState, commerce.auth.store.getState);
+    return reviewAbility(state);
+}
+//# sourceMappingURL=use-reviews.js.map

package/dist/use-shop-address.d.ts

@@ -0,0 +1,12 @@
+import type { AddressOptions } from '@webround/commerce';
+import type { ShopStore } from '@webround/commerce';
+export interface UseShopAddressOptions extends AddressOptions {
+    /** The query string of the address NOW, as the router gives it (`location.search`). */
+    search: string;
+    /** Goes to this query string, on the same page, adding a history entry (`navigate({ search })` of react-router). */
+    navigate: (search: string) => void;
+    /** The collection the page is for (from its route): it is not in the query. */
+    collectionId?: string;
+}
+export declare function useShopAddress(options: UseShopAddressOptions): ShopStore;
+//# sourceMappingURL=use-shop-address.d.ts.map

package/dist/use-shop-address.js

@@ -0,0 +1,39 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { createAddressShopStore } from '@webround/commerce';
+export function useShopAddress(options) {
+    const { search, collectionId, limit } = options;
+    // What the port calls is always the latest the site gave, without the store being made again at every render
+    const navigate = useRef(options.navigate);
+    navigate.current = options.navigate;
+    const listeners = useRef(new Set());
+    // What the address says now: what the router said last, or what was written since (until the router says it too)
+    const shown = useRef(search);
+    const routerSaid = useRef(search);
+    // The router says something else than before (the back button, a link): THAT is the address, already in this render (no frame with the old one). Only a change of what the router says counts:
+    // a render that comes between a write and the router's answer must not take the address back.
+    if (routerSaid.current !== search) {
+        routerSaid.current = search;
+        shown.current = search;
+    }
+    const port = useMemo(() => ({
+        read: () => shown.current,
+        write(next) {
+            shown.current = next;
+            for (const listener of [...listeners.current])
+                listener();
+            navigate.current(next);
+        },
+        subscribe(listener) {
+            listeners.current.add(listener);
+            return () => { listeners.current.delete(listener); };
+        },
+    }), []);
+    // Whoever listens (another component with the same store) is told that the address may have changed: if what the shop says is the same, it is the same state and nothing is drawn again
+    useEffect(() => {
+        for (const listener of [...listeners.current])
+            listener();
+    }, [search]);
+    // A new store when the page's collection or the shop's limit change: it is the same address read with other defaults
+    return useMemo(() => createAddressShopStore(port, { collectionId, limit }), [port, collectionId, limit]);
+}
+//# sourceMappingURL=use-shop-address.js.map

package/dist/use-shop.d.ts

@@ -0,0 +1,34 @@
+import type { CachedCatalog } from '@webround/commerce';
+import type { ProductPage, ProductSearch, StoreDataResponse } from '@webround/commerce';
+import { type SortOption } from '@webround/commerce';
+import type { ShopState } from '@webround/commerce';
+import { type ShopActions, type ShopStore } from '@webround/commerce';
+import type { SearchContext } from '@webround/commerce';
+import { type UseResourceResult } from './use-resource.js';
+export interface UseShopOptions {
+    catalog: CachedCatalog;
+    /** What the question needs besides what the customer chose: the currency, the language, the cadence, what the products are loaded with. */
+    context: SearchContext;
+    /** The state the shop starts in (only when the hook keeps the state itself: it is not read again). */
+    initial?: ShopState;
+    /** Where the state lives, when it is not in memory in the hook (an address bar, a store the page owns). */
+    store?: ShopStore;
+    /** While a new question is awaited, keep showing the answer to the one before (marked `isStale`), so a listing does not empty at every click. On by default. */
+    keepPrevious?: boolean;
+}
+export interface UseShopResult {
+    /** What the customer chose. */
+    state: ShopState;
+    /** What changes it. */
+    actions: ShopActions;
+    /** The store's own data (its tags, collections, filters, currencies): what the controls are drawn from. */
+    storeData: UseResourceResult<StoreDataResponse>;
+    /** The orders that can be offered now (with the store's data in hand, and a text or not); none until it is. */
+    sortOptions: SortOption[];
+    /** The question the catalog is being asked now, or null while the store's data is awaited. */
+    question: ProductSearch | null;
+    /** The products. While the store's data is awaited this is `pending` (or its error, with a `retry` that asks for the store again). */
+    results: UseResourceResult<ProductPage>;
+}
+export declare function useShop(options: UseShopOptions): UseShopResult;
+//# sourceMappingURL=use-shop.d.ts.map

package/dist/use-shop.js

@@ -0,0 +1,31 @@
+import { useCallback, useMemo, useRef, useSyncExternalStore } from 'react';
+import { canonicalJson } from '@webround/commerce';
+import { shopQuestion } from '@webround/commerce';
+import { sortOptionsOf } from '@webround/commerce';
+import { createShopStore, shopActions } from '@webround/commerce';
+import { useResource } from './use-resource.js';
+export function useShop(options) {
+    const { catalog, context, keepPrevious = true } = options;
+    // The state: in memory, in the hook, unless a store was given
+    const own = useRef(null);
+    if (!options.store && !own.current)
+        own.current = createShopStore(options.initial);
+    const store = options.store ?? own.current;
+    const state = useSyncExternalStore(store.subscribe, store.getState, store.getState);
+    const actions = useMemo(() => shopActions(store), [store]);
+    const storeData = useResource(catalog.resource.storeData.get(context.langCode === undefined ? undefined : { langCode: context.langCode }));
+    const data = storeData.data?.data;
+    // A new `context` object at every render is the same context: only what is in it makes a new question
+    const contextKey = canonicalJson(context);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    const asked = useMemo(() => shopQuestion(catalog, data, state, context), [catalog, data, state, contextKey]);
+    const products = useResource(asked?.resource ?? null, { keepPrevious });
+    const sortOptions = useMemo(() => (data ? sortOptionsOf(data) : []), [data]);
+    // With no question yet the products are waiting for the store's data (or failed with it): say that, so the screen has one thing to look at
+    const retry = useCallback(() => storeData.retry(), [storeData]);
+    const results = asked
+        ? products
+        : { status: storeData.status === 'error' ? 'error' : 'pending', data: undefined, error: storeData.error, isFetching: storeData.status !== 'error', isStale: false, retry };
+    return { state, actions, storeData, sortOptions, question: asked?.question ?? null, results };
+}
+//# sourceMappingURL=use-shop.js.map

package/dist/use-wishlist.d.ts

@@ -0,0 +1,15 @@
+import { type Wishlist, type WishlistState } from '@webround/commerce';
+export interface UseWishlistResult {
+    state: WishlistState;
+    count: number;
+    /** Whether a variant is in the wishlist. */
+    has(variantId: string): boolean;
+    /** The switch: adds a variant that is not in the wishlist, removes one that is. Throws what the store refuses; `LOGIN_REQUIRED` for a guest. */
+    toggle: Wishlist['toggle'];
+    refresh: Wishlist['refresh'];
+}
+/** `commerce` is what `createCommerce` made (or `@webround/commerce-react/site`'s). Any number of components can use it (a heart on each product): the wishlist starts once. A server render says `unknown` and nothing in it. */
+export declare function useWishlist(commerce: {
+    wishlist: Wishlist;
+}): UseWishlistResult;
+//# sourceMappingURL=use-wishlist.d.ts.map

package/dist/use-wishlist.js

@@ -0,0 +1,12 @@
+import { useCallback, useEffect, useMemo, useSyncExternalStore } from 'react';
+import { isInWishlist } from '@webround/commerce';
+/** `commerce` is what `createCommerce` made (or `@webround/commerce-react/site`'s). Any number of components can use it (a heart on each product): the wishlist starts once. A server render says `unknown` and nothing in it. */
+export function useWishlist(commerce) {
+    const { wishlist } = commerce;
+    const state = useSyncExternalStore(wishlist.subscribe, wishlist.getState, wishlist.getState);
+    useEffect(() => { void wishlist.start(); }, [wishlist]);
+    const has = useCallback((variantId) => isInWishlist(state, variantId), [state.variantIds]);
+    const actions = useMemo(() => ({ toggle: (variantId) => wishlist.toggle(variantId), refresh: () => wishlist.refresh() }), [wishlist]);
+    return { state, count: state.count, has, toggle: actions.toggle, refresh: actions.refresh };
+}
+//# sourceMappingURL=use-wishlist.js.map

package/package.json

@@ -1,6 +1,47 @@
 {
-  "name": "@webround/commerce-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@webround/commerce-react",
+    "version": "0.3.0",
+    "type": "module",
+    "main": "./dist/index.js",
+    "module": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts",
+            "development": "./src/index.ts"
+        },
+        "./site": {
+            "import": "./dist/site.js",
+            "types": "./dist/site.d.ts",
+            "development": "./src/site.ts"
+        }
+    },
+    "files": [
+        "dist",
+        "!dist/**/*.map"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsc --watch",
+        "test": "node --test test/*.test.ts",
+        "typecheck": "tsc --noEmit -p tsconfig.test.json"
+    },
+    "peerDependencies": {
+        "@webround/commerce": "^0.3.0",
+        "@webround/core": "^0.3.0",
+        "react": ">=19"
+    },
+    "devDependencies": {
+        "@types/jsdom": "^30.0.0",
+        "@types/react": "^19.3.0",
+        "@types/react-dom": "^19.3.0",
+        "jsdom": "^26.1.0",
+        "react": "^19.3.0",
+        "react-dom": "^19.3.0",
+        "typescript": "^5.5.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.