@calimero-network/mero-react 9.13.2 → 9.14.1

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
@@ -264,6 +264,52 @@ import {
264
264
 
265
265
  These are used internally by `MeroProvider` but exported for apps that need direct access.
266
266
 
267
+ ### Invitations by link
268
+
269
+ An invitation reaches an app only by its link being opened: `https://links.calimero.network/<package>/join?invitation=…`. The links page opens the app with `?invitation=…` appended, and a desktop app that is already open receives a `deep-link` event. This module covers that path end to end:
270
+
271
+ ```tsx
272
+ import {
273
+ primeInvitationCapture,
274
+ useInviteRedemption,
275
+ InvitationDialog,
276
+ buildInviteLink,
277
+ } from '@calimero-network/mero-react';
278
+
279
+ // main.tsx, before the router runs: take the link from the URL or the desktop
280
+ // bridge and buffer it until something asks.
281
+ primeInvitationCapture('my-app', { slug: 'com.example.my-app' });
282
+
283
+ // The app root, once: ask, join, wait for the data, done.
284
+ function Invitations() {
285
+ const redemption = useInviteRedemption({
286
+ parse: (token) => decodeMyToken(token), // { namespaceId, invitation, teamName? }
287
+ redeemer: { join, isMember }, // mero-js `InviteRedeemer`
288
+ onJoined: (namespaceId) => navigate(`/w/${namespaceId}`),
289
+ });
290
+ return <InvitationDialog redemption={redemption} noun="workspace" appName="My App" />;
291
+ }
292
+
293
+ // Sharing: one link shape for every app.
294
+ const link = buildInviteLink('com.example.my-app', token);
295
+ ```
296
+
297
+ An app whose join does more than join the namespace (entering a context, choosing where to land) passes `redeem: (parsed) => Promise<RedeemOutcome>` instead of `redeemer`; `parse` may return extra fields, which reach `redeem` and come back as `parsed`. The dialog takes `detail` (the app's own words under the question) and `status` (the step a slow join is on).
298
+
299
+ `InvitationDialog` walks through every stage in one modal: **ask** (Join / Not now) → **joining** (cannot be closed) → **syncing** → **ready** (closes by itself), or **already a member**, or **failed** (the reason in plain words, with Try again when a retry can help).
300
+
301
+ **Syncing** lasts until the joined namespace's data has arrived. Redemption marks the namespace just-joined, and the page that reads its data clears that mark:
302
+
303
+ ```tsx
304
+ // The page showing the namespace: `settled` once a read has come back,
305
+ // including an empty one.
306
+ const { isSyncing, dismiss } = useJoinSync({ namespaceId, settled: !loading });
307
+ ```
308
+
309
+ An app whose root already knows can pass `synced` to the dialog instead. A sync that never settles says so after `JOIN_SYNC_WATCHDOG_MS` and lets go at `JOIN_SYNC_MAX_MS`. `JoinSyncBanner` is the matching in-page strip.
310
+
311
+ The dialog is styled with the same `--mero-*` variables as `<ConnectButton>` and `<LoginModal>` (see [Theming](#theming)). Its test ids are `invite-prompt` (with `data-stage`), `invite-accept`, `invite-decline`, `invite-continue`, `invite-done`, `invite-retry` and `invite-error`.
312
+
267
313
  ### Re-exports from mero-js
268
314
 
269
315
  mero-react re-exports everything from mero-js via `export * from '@calimero-network/mero-js'`. Any new API added to mero-js is automatically available from mero-react — no manual sync needed.