@webround/commerce-react 0.3.14 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { useResource } from './use-resource.js';
-export type { UseResourceOptions, UseResourceResult } from './use-resource.js';
+export type { UseResourceOptions, UseResourceResult, UseResourceState } from './use-resource.js';
+export { storeContentOf, useStoreData } from './use-store-data.js';
+export type { StoreContent, UseStoreDataResult } from './use-store-data.js';
 export { useShop } from './use-shop.js';
 export type { UseShopOptions, UseShopResult } from './use-shop.js';
 export { useShopAddress } from './use-shop-address.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 // @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 { storeContentOf, useStoreData } from './use-store-data.js';
 export { useShop } from './use-shop.js';
 export { useShopAddress } from './use-shop-address.js';
 export { authActions, useAuth } from './use-auth.js';

package/dist/use-resource.d.ts

@@ -6,11 +6,27 @@ export interface UseResourceOptions {
      */
     keepPrevious?: boolean;
 }
-export interface UseResourceResult<T> {
+/**
+ * What `data` is. The backends wrap a list or a record as `{ data, pagination… }`; a component wants the list, not the wrapper, so an answer that has a `data` key is opened: its `data` is `data`, and each of
+ * its other keys (`pagination`, `breakdown`) is a key of the result, next to it. An answer with no `data` key (an order, a return) is `data` as it is. One rule, for every hook.
+ */
+export type Payload<T> = T extends {
+    data: infer D;
+} ? D : T;
+/** The keys of the wrapper that are not `data`: there from the moment the answer is, `undefined` before. */
+export type Beside<T> = T extends {
+    data: unknown;
+} ? Partial<Omit<T, 'data'>> : unknown;
+/** The answer in the shape a component reads it (see `Payload`). The wrapper's other keys never meet the result's own (`status`, `error`…): the result's are written last, and a test keeps the backends from taking one. */
+export declare function presented<T>(answer: T | undefined): {
+    data: Payload<T> | undefined;
+} & Beside<T>;
+export type UseResourceResult<T> = UseResourceState<Payload<T>> & Beside<T>;
+export interface UseResourceState<D> {
     /** `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;
+    /** The answer to what is asked (the list, the record: never the backend's wrapper), or (with `keepPrevious`, while the new one is awaited) the answer to the question before; undefined when there is none. */
+    data: D | 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. */

package/dist/use-resource.js

@@ -1,4 +1,9 @@
 import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+/** The answer in the shape a component reads it (see `Payload`). The wrapper's other keys never meet the result's own (`status`, `error`…): the result's are written last, and a test keeps the backends from taking one. */
+export function presented(answer) {
+    const wrapped = typeof answer === 'object' && answer !== null && 'data' in answer;
+    return (wrapped ? { ...answer } : { data: answer });
+}
 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). */
@@ -47,14 +52,15 @@ export function useResource(resource, options = {}) {
             hasShown.current = true;
         }
     }, [snapshot]);
+    const result = (state, answer) => ({ ...presented(answer), ...state });
     if (!asked)
-        return { status: 'idle', data: undefined, error: undefined, isFetching: false, isStale: false, retry };
+        return result({ status: 'idle', error: undefined, isFetching: false, isStale: false, retry }, undefined);
     if (snapshot.status === 'ready')
-        return { status: 'ready', data: snapshot.data, error: undefined, isFetching: false, isStale: false, retry };
+        return result({ status: 'ready', error: undefined, isFetching: false, isStale: false, retry }, snapshot.data);
     if (snapshot.status === 'error')
-        return { status: 'error', data: undefined, error: snapshot.error, isFetching: false, isStale: false, retry };
+        return result({ status: 'error', error: snapshot.error, isFetching: false, isStale: false, retry }, undefined);
     // `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 };
+    return result({ status: 'pending', error: undefined, isFetching: true, isStale: stale, retry }, stale ? shown.current : undefined);
 }
 //# sourceMappingURL=use-resource.js.map

package/dist/use-shop.d.ts

@@ -1,10 +1,11 @@
 import type { CachedCatalog } from '@webround/commerce';
-import type { ProductPage, ProductSearch, StoreDataResponse } from '@webround/commerce';
+import type { Pagination, ProductSearch, ProductSummary } 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';
+import { type UseResourceState } from './use-resource.js';
+import { type StoreContent } from './use-store-data.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. */
@@ -16,19 +17,20 @@ export interface UseShopOptions {
     /** 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. */
+/** The products and how they are being asked: `status` and the rest are about THE PRODUCTS (they say `pending` or `error` while the store's data, which the question needs, is awaited or failed). */
+export interface UseShopResult extends StoreContent, Omit<UseResourceState<ProductSummary[]>, 'data'> {
+    /** What the customer chose: the collection, the text, the tag values and ranges, the order, the page. */
     state: ShopState;
-    /** What changes it. */
+    /** What changes it. Every change that is not `setPage` goes back to page 1. */
     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. */
+    /** The exact question the catalog is being asked now (`state` made a request, with `context`), or `null` while the store's data is awaited. The `products` are its answer. */
     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>;
+    /** The products of the page the customer is at, for `question`. `undefined` until they are there; while the next page is awaited, with `keepPrevious`, the page before (`isStale`). */
+    products: ProductSummary[] | undefined;
+    /** How many products and pages there are for `question`, and which page this is. `undefined` when `products` is. */
+    pagination: Pagination | undefined;
 }
 export declare function useShop(options: UseShopOptions): UseShopResult;
 //# sourceMappingURL=use-shop.d.ts.map

package/dist/use-shop.js

@@ -4,6 +4,7 @@ import { shopQuestion } from '@webround/commerce';
 import { sortOptionsOf } from '@webround/commerce';
 import { createShopStore, shopActions } from '@webround/commerce';
 import { useResource } from './use-resource.js';
+import { useStoreData } from './use-store-data.js';
 export function useShop(options) {
     const { catalog, context, keepPrevious = true } = options;
     // The state: in memory, in the hook, unless a store was given
@@ -13,19 +14,21 @@ export function useShop(options) {
     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;
+    const storeData = useStoreData(catalog, context.langCode);
+    const { status: storeStatus, error: storeError, retry: retryStore, ...content } = storeData;
+    const loaded = content.store !== undefined;
     // 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 asked = useMemo(() => shopQuestion(catalog, loaded ? content : null, state, context), [catalog, storeData, state, contextKey]);
     const products = useResource(asked?.resource ?? null, { keepPrevious });
-    const sortOptions = useMemo(() => (data ? sortOptionsOf(data) : []), [data]);
+    const sortOptions = useMemo(() => (loaded ? sortOptionsOf(content) : []), [storeData]);
     // 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
+    const retry = useCallback(() => retryStore(), [retryStore]);
+    const listing = 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 };
+        : { status: storeStatus === 'error' ? 'error' : 'pending', data: undefined, error: storeError, isFetching: storeStatus !== 'error', isStale: false, retry };
+    const { data, pagination, ...how } = listing;
+    return { ...content, state, actions, sortOptions, question: asked?.question ?? null, products: data, pagination, ...how };
 }
 //# sourceMappingURL=use-shop.js.map

package/dist/use-store-data.d.ts

@@ -0,0 +1,25 @@
+import type { CachedCatalog, StoreAttribute, StoreCollection, StoreData, StoreFilter, StoreSettings, StoreTag } from '@webround/commerce';
+import { type UseResourceResult } from './use-resource.js';
+/** What the store's data says, by name. The lists are empty until the data is there; `store` is `undefined` until then (it is how a component knows the data has come). */
+export interface StoreContent {
+    /** The store's settings: its currency, cadence, the languages and currencies it offers. `undefined` until the data is there. */
+    store: StoreSettings | undefined;
+    /** Every collection, as a tree (the children are in `children`); the invisible ones too (`visible`). */
+    collections: StoreCollection[];
+    /** The tags, each with its values. */
+    tags: StoreTag[];
+    attributes: StoreAttribute[];
+    /** The filters a customer can set (ranges: a price, a number, a date). */
+    filters: StoreFilter[];
+}
+export interface UseStoreDataResult extends StoreContent {
+    /** `pending` until the store's data is there, `error` if it could not be had (`retry` asks again). */
+    status: UseResourceResult<unknown>['status'];
+    error: unknown;
+    retry: () => void;
+}
+/** The store's data by name. Pure: the same data gives the same lists (the same arrays). */
+export declare function storeContentOf(data: StoreData | undefined): StoreContent;
+/** `langCode` is the language the names are asked in (left out: the store's own). */
+export declare function useStoreData(catalog: Pick<CachedCatalog, 'resource'>, langCode?: string): UseStoreDataResult;
+//# sourceMappingURL=use-store-data.d.ts.map

package/dist/use-store-data.js

@@ -0,0 +1,17 @@
+import { useMemo } from 'react';
+import { useResource } from './use-resource.js';
+// ONE empty content: the lists before the data is there are always the same arrays, so what depends on them is not drawn again for nothing
+const NOT_THERE = { store: undefined, collections: [], tags: [], attributes: [], filters: [] };
+/** The store's data by name. Pure: the same data gives the same lists (the same arrays). */
+export function storeContentOf(data) {
+    if (!data)
+        return NOT_THERE;
+    return { store: data.store, collections: data.collections, tags: data.tags, attributes: data.attributes, filters: data.filters };
+}
+/** `langCode` is the language the names are asked in (left out: the store's own). */
+export function useStoreData(catalog, langCode) {
+    const answer = useResource(catalog.resource.storeData.get(langCode === undefined ? undefined : { langCode }));
+    const content = useMemo(() => storeContentOf(answer.data), [answer.data]);
+    return useMemo(() => ({ ...content, status: answer.status, error: answer.error, retry: answer.retry }), [content, answer.status, answer.error, answer.retry]);
+}
+//# sourceMappingURL=use-store-data.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webround/commerce-react",
-    "version": "0.3.14",
+    "version": "0.4.0",
     "type": "module",
     "main": "./dist/index.js",
     "module": "./dist/index.js",
@@ -28,8 +28,8 @@
         "typecheck": "tsc --noEmit -p tsconfig.test.json"
     },
     "peerDependencies": {
-        "@webround/commerce": "^0.3.0",
-        "@webround/core": "^0.3.0",
+        "@webround/commerce": "^0.4.0",
+        "@webround/core": "^0.4.0",
         "react": ">=19"
     },
     "devDependencies": {