@moonbase.sh/react 0.0.0-next-20261111171316 → 0.0.0-next-20261111171855

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -31,7 +31,8 @@ createRoot(document.getElementById('root')!).render(
31
31
 
32
32
  Make the storefront at module level, not in a component: it reads the address the visitor arrived at, keeps the cart
33
33
  in step with other tabs, and coming back from the hosted checkout it reopens the checkout and takes Moonbase's `mb_*`
34
- parameters off the address. Make it before your router, which reads the address as it is made.
34
+ parameters off the address. Make it before your router, which reads the address as it is made. Where it has to be made
35
+ in a component, such as from a catalog the server fetched, use `getStorefront` (see [Server rendering](#server-rendering)).
35
36
 
36
37
  ## Use hooks in components
37
38
 
@@ -96,9 +97,13 @@ identity across renders, so it can go in a dependency list or to a memoized chil
96
97
  - `useInventory()` - owned products, licenses and the computers they're activated on, downloads, and subscriptions:
97
98
  cancelling, renewing, changing plan and changing the card they're paid with.
98
99
  - `useOrders()` - the signed-in customer's completed orders, newest first, and their receipt PDFs.
100
+ - `useOwnedProducts()`, `useOwnedProduct(id)`, `useProductActivations(id)`, `useProductLicenses(id)`,
101
+ `useOrderHistory()`, `useSubscriptions()`, `useSubscription(id)` - the signed-in customer's account data, loaded for
102
+ you (see [Account pages](#account-pages)).
99
103
  - `useVoucher()` - what a voucher code gives, and redeeming it.
100
- - `useActivationRequest(token)` - activating a product in the browser: the request the app made, granting it a license
101
- or a trial, and waiting for the app to pick it up.
104
+ - `useActivationRequest(token, options)` - activating a product in the browser: the request the app made, granting it a
105
+ license or a trial, and waiting for the app to pick it up. With `{ autoFulfill: true }` it activates with the signed-in
106
+ customer's license as soon as the request says they can, once per request, leaving a failure in `error`.
102
107
  - `useGroups()` - join the signed-in customer to a customer list of the store's that has been opened to sign-ups.
103
108
  Throws `NotFoundError` for every reason a join can be refused, which the API deliberately does not distinguish.
104
109
  - `useReviews()` - product reviews: `enabled` says whether the store takes them, `getReviews` and `getMoreReviews` read
@@ -108,7 +113,8 @@ identity across renders, so it can go in a dependency list or to a memoized chil
108
113
  - `useCommunicationPreferences()` - newsletter sign-ups, and the preferences page an email's footer links to.
109
114
  - `useVendor()` - who runs the store.
110
115
  - `useStorefront()` - the storefront itself, and `useStorefrontState(state => ...)` for any part of its state
111
- (`attributionConsentStatus`, `catalog`, `catalogLoaded`, `closed`, `order`, `user`, `userLoaded`, `utm`).
116
+ (`attributionConsentRequired`, `attributionConsentStatus`, `catalog`, `catalogLoaded`, `closed`, `order`, `user`,
117
+ `userLoaded`, `utm`).
112
118
 
113
119
  ### Where checkout happens
114
120
 
@@ -155,6 +161,45 @@ function CheckoutButton() {
155
161
  }
156
162
  ```
157
163
 
164
+ ## Account pages
165
+
166
+ The account data hooks load what they show for whoever is signed in, and load it again when that changes. Each returns
167
+ `{ data, loading, error, reload }`, and the lists, which Moonbase hands out a page at a time, add `hasMore` and
168
+ `loadMore`, with `data` holding every page loaded so far:
169
+
170
+ ```tsx
171
+ import { useOrderHistory } from '@moonbase.sh/react'
172
+
173
+ function Purchases() {
174
+ const orders = useOrderHistory()
175
+
176
+ if (orders.error)
177
+ return <p role="alert">{orders.error.message}</p>
178
+ if (!orders.data)
179
+ return <p>Loading…</p>
180
+
181
+ return (
182
+ <>
183
+ {orders.data.length === 0 && <p>No purchases yet.</p>}
184
+ <ul>
185
+ {orders.data.map(order => <li key={order.id}>{order.id}</li>)}
186
+ </ul>
187
+ {orders.hasMore && (
188
+ <button disabled={orders.loading} onClick={orders.loadMore}>Show more</button>
189
+ )}
190
+ </>
191
+ )
192
+ }
193
+ ```
194
+
195
+ `data` is null while it first loads, with nobody signed in, and for an ID of `null` or `undefined`, which asks for nothing.
196
+ `loading` is true while a request is in flight and until the storefront knows who is signed in, so a page doesn't flash
197
+ "Nothing here" before it does. What a hook loaded is kept for as long as the same customer is signed in: a component
198
+ that mounts again, such as a tab the customer comes back to, shows it at once and asks again in the background.
199
+ Components asking for the same thing at once share one request. After changing something, call `reload`, which goes
200
+ back to a list's first page. `reload` and `loadMore` never reject: a failure lands in `error`, and `data` keeps what was
201
+ there.
202
+
158
203
  ## Checkout events
159
204
 
160
205
  ```tsx
@@ -188,6 +233,10 @@ your page is not loaded then: subscribe a webhook to `OrderPaymentFailed` to fol
188
233
 
189
234
  Outside of React, `storefront.on('checkoutCompleted', order => ...)` does the same and returns the function that stops it.
190
235
 
236
+ `useStorefrontEvent` starts listening once its component has mounted, so it misses what the storefront reported before
237
+ then, such as the first `catalogUpdated` on a slow phone. Read what a page needs from the start from the state with
238
+ `useStorefrontState`, or subscribe with `storefront.on` where the storefront is made.
239
+
191
240
  ## Outside of components
192
241
 
193
242
  Nothing in the storefront depends on React, so a router loader, an analytics script or your own store can use it
@@ -238,6 +287,28 @@ cookies as each request is made) and the page's origin and path. `storefront.adS
238
287
  or `'unknown'`). When your banner reports a refusal for a signed-in customer, the storefront tells Moonbase, once per
239
288
  tab.
240
289
 
290
+ `attributionConsentRequired` in the state says whether the store's setting asks this visitor at all: `true` or `false`
291
+ once the browser has loaded the catalog for them, and `undefined` until then, since a catalog fetched on a server
292
+ describes where the server is. A banner of your own asks when the store asks and nobody has answered yet:
293
+
294
+ ```tsx
295
+ function CookieBanner() {
296
+ const required = useStorefrontState(state => state.attributionConsentRequired)
297
+ const status = useStorefrontState(state => state.attributionConsentStatus)
298
+ const storefront = useStorefront()
299
+
300
+ if (!required || status !== 'unknown')
301
+ return null
302
+
303
+ return (
304
+ <div role="dialog">
305
+ <button onClick={() => storefront.setAttributionConsent(true)}>Accept</button>
306
+ <button onClick={() => storefront.setAttributionConsent(false)}>Decline</button>
307
+ </div>
308
+ )
309
+ }
310
+ ```
311
+
241
312
  ## Server rendering
242
313
 
243
314
  `fetchCatalog(endpoint, options)` fetches the catalog on a server, as anyone sees it, for the `initialCatalog` a page's
@@ -253,13 +324,26 @@ storefront made at module level in a client module, as above, renders on the ser
253
324
  own fallback prices until it loads, and the browser takes over from there. The browser hydrates against that same
254
325
  server state before switching to its own, so a catalog it cached on an earlier visit never causes a hydration mismatch.
255
326
 
256
- To have the server render real prices, fetch the catalog there and start the page's storefront from it:
327
+ To have the server render real prices, fetch the catalog there and start the page's storefront from it. The storefront
328
+ is then made in a component, so make it with `getStorefront`, which hands back the same storefront every time in a
329
+ browser and a new one for each render on a server:
257
330
 
258
331
  ```tsx
259
332
  'use client'
260
333
 
261
334
  export function Providers({ catalog, children }: { catalog: Storefront, children: ReactNode }) {
262
- const [storefront] = useState(() => createStorefront('https://demo.moonbase.sh', { initialCatalog: catalog }))
335
+ const storefront = getStorefront('https://demo.moonbase.sh', { initialCatalog: catalog })
263
336
  return <StorefrontProvider storefront={storefront}>{children}</StorefrontProvider>
264
337
  }
265
338
  ```
339
+
340
+ Not `createStorefront` in a `useState` initializer: React runs one twice under Strict Mode, and the storefront it throws
341
+ away would go on following the tab. The options only count the first time, when the storefront is made.
342
+
343
+ A router that reads the address before the storefront is made, as Next.js's does, puts the hosted checkout's `mb_*`
344
+ parameters back as the page hydrates. `<StorefrontProvider>` takes them off again once the page has hydrated, and tells
345
+ the router with a `popstate`, so `useSearchParams()` no longer lists them either.
346
+
347
+ `storefront.dispose()` stops a storefront for good: it stops following other tabs and the checkout, stops renewing the
348
+ customer's sign-in, and ignores what its requests still in flight bring back. That is for tests, or a page that swaps one
349
+ storefront for another. After it, `getStorefront` makes a new one.