@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 +90 -6
- package/dist/index.cjs +326 -84
- package/dist/index.d.cts +145 -15
- package/dist/index.d.ts +145 -15
- package/dist/index.js +290 -56
- package/package.json +2 -2
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
|
|
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`,
|
|
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
|
|
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.
|