@xyo-network/xl1-react-client-sdk 5.6.0 → 5.6.2

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
@@ -86,6 +86,24 @@ reason (a non-Error reason is retained as the cause of an AbortError). `useClien
86
86
  injection listener until unmount. Discovery only observes the injected client;
87
87
  it does not request permissions or sign actions.
88
88
 
89
+ ### Account access
90
+
91
+ `ConnectAccountsStack`, and the `useConnectAccount` hook behind it, reads this
92
+ site's existing wallet grant before offering to connect. `isLoading` stays true
93
+ until wallet discovery and that first read finish, and the connect control is
94
+ rendered only when no account is shared, so the stack never requests a grant
95
+ that already exists. The grant is read again after each `requestAccounts()`
96
+ and whenever the window regains focus, so accounts added in the wallet's
97
+ prompt and access revoked in the wallet appear without a remount.
98
+
99
+ A grant is the set of accounts a site may use, not a choice of one: the XL1
100
+ wallet merges each request into it as a set union. `accounts`, and the stack's
101
+ `onAccountsChanged` callback, list every granted account in grant order. Keep
102
+ the account your dApp acts as in your own state and let the user choose it.
103
+ For compatibility, `address`, `connectSigner()`, and `onAccountConnected`
104
+ still report only the first granted account. `useGrantedAccounts(permissions)`
105
+ tracks the same grant for a permissions provider you already hold.
106
+
89
107
  ## Documentation
90
108
 
91
109
  Public subpaths:
@@ -4,18 +4,32 @@ import type { ComponentType, MouseEventHandler } from 'react';
4
4
  import React from 'react';
5
5
  /** Props accepted by the Connect Client Accounts Stack component. */
6
6
  export interface ConnectClientAccountsStackProps extends StackProps {
7
- /** Component used to render the connected account. */
7
+ /**
8
+ * Component used to render each granted account. It receives the account as
9
+ * `address`, and as `account` for compatibility with this prop's earlier type.
10
+ */
8
11
  AccountComponent?: ComponentType<{
9
- account?: string;
12
+ account?: XyoAddress;
13
+ address: XyoAddress;
10
14
  }>;
11
15
  /** Component used to initiate the wallet connection flow. */
12
16
  ConnectComponent?: ComponentType<{
13
17
  onClick?: MouseEventHandler<HTMLElement>;
14
18
  }>;
19
+ /** Component shown while wallet discovery or the first grant read is pending. */
20
+ LoadingComponent?: ComponentType;
15
21
  /** Component shown after wallet discovery times out. */
16
22
  NoWalletInstalledComponent?: ComponentType;
17
- /** Callback invoked after an account connection succeeds. */
23
+ /**
24
+ * Callback invoked with the first granted account whenever it changes. A grant
25
+ * can hold several accounts; use `onAccountsChanged` to let the user choose.
26
+ */
18
27
  onAccountConnected?: (account: XyoAddress) => void;
28
+ /**
29
+ * Callback invoked with every account the wallet lets this site use, after each
30
+ * grant read that changes them, including `[]` when access is revoked.
31
+ */
32
+ onAccountsChanged?: (accounts: readonly XyoAddress[]) => void;
19
33
  /** Callback invoked when the connection flow is cancelled. */
20
34
  onCancel?: () => void;
21
35
  /** Maximum time to wait for the wallet operation, in milliseconds. */
@@ -26,33 +40,43 @@ export interface ConnectClientAccountsStackProps extends StackProps {
26
40
  * connection to an XL1 wallet (e.g. the XL1 Chrome extension) and lets them
27
41
  * kick off a connection.
28
42
  *
29
- * Connection state is derived from `useConnectAccount`, which wraps
30
- * `useGatewayFromWallet` (wallet/gateway discovery with a configurable
31
- * `timeout`) and `useAccountPermissions` (already-authorized addresses).
32
- * The hook returns: `address` (resolved once the wallet exposes one),
33
- * `connectSigner` (prompts the wallet for an address), `timedout` (the
34
- * gateway never appeared within `timeout`), and `error` (the first of
35
- * gateway, permissions, or signer-connect failures).
43
+ * Connection state is derived from `useConnectAccount`, which discovers the
44
+ * wallet within a configurable `timeout` and follows this site's account
45
+ * grant with `useGrantedAccounts`. The hook returns: `accounts` (every account
46
+ * the wallet lets this site use), `isLoading` (discovery or the first grant
47
+ * read is pending), `requestAccounts` (opens the wallet's consent prompt, then
48
+ * reads the grant again), `timedout` (no wallet appeared within `timeout`), and
49
+ * `error` (the first of discovery, grant read, or request failures). The grant
50
+ * is also re-read when the window regains focus, so accounts added in the
51
+ * wallet and access revoked there show up without a remount.
36
52
  *
37
53
  * The component renders exactly one of the following wallet states, plus
38
54
  * an always-present error slot:
39
55
  *
40
- * - **Connected** — `address` is defined: renders `AccountComponent` for
41
- * that address. Also fires `onAccountConnected(address)` once via effect.
42
- * - **Disconnected, wallet available** — no `address` and not `timedout`:
43
- * renders `ConnectComponent` as a "Connect" button that invokes
44
- * `connectSigner()`. This covers both "wallet installed but no account
45
- * authorized yet" and "gateway still resolving".
46
- * - **Wallet missing / unreachable** — no `address` and `timedout` is true:
56
+ * - **Checking** — `isLoading` is true: renders `LoadingComponent` (defaults to
57
+ * a disabled, busy "Connect" button). `ConnectComponent` is not rendered until
58
+ * the grant has been read, so it never requests access that already exists.
59
+ * - **Connected** — the grant holds accounts: renders `AccountComponent` for
60
+ * each of them. Fires `onAccountsChanged(accounts)` and, for compatibility,
61
+ * `onAccountConnected` with the first account, via effects.
62
+ * - **No access, wallet available** — the grant is empty, or no grant read has
63
+ * succeeded, and not `timedout`: renders `ConnectComponent` as a "Connect"
64
+ * button that invokes `requestAccounts()`. A failed re-read keeps the
65
+ * accounts last read, so a transient failure does not offer to connect again.
66
+ * - **Wallet missing / unreachable** — no accounts and `timedout` is true:
47
67
  * renders `NoWalletInstalledComponent` (defaults to an Alert linking to
48
68
  * the XL1 Wallet Chrome Web Store listing).
49
69
  * - **Error** — any error from the hook is rendered via `ErrorRender`
50
70
  * alongside the state above, and `onCancel()` is fired once via effect
51
71
  * so the host UI can close/abort its connect flow.
52
72
  *
53
- * All three slot components (`AccountComponent`, `ConnectComponent`,
54
- * `NoWalletInstalledComponent`) are injectable so consumers can restyle
55
- * any state without forking this component.
73
+ * A grant is the set of accounts the site may use, not a choice of one: to
74
+ * pick the account the dApp acts as, keep that choice in the dApp and offer
75
+ * the accounts from `onAccountsChanged`.
76
+ *
77
+ * All four slot components (`AccountComponent`, `ConnectComponent`,
78
+ * `LoadingComponent`, `NoWalletInstalledComponent`) are injectable so
79
+ * consumers can restyle any state without forking this component.
56
80
  */
57
81
  export declare const ConnectAccountsStack: React.FC<ConnectClientAccountsStackProps>;
58
82
  //# sourceMappingURL=ConnectAccountsStack.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"ConnectAccountsStack.d.ts","sourceRoot":"","sources":["../../../../../src/client/components/connected/ConnectAccountsStack.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAK/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAC7D,OAAO,KAAoB,MAAM,OAAO,CAAA;AA6BxC,qEAAqE;AACrE,MAAM,WAAW,+BAAgC,SAAQ,UAAU;IACjE,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,aAAa,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACtD,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,aAAa,CAAC;QAAE,OAAO,CAAC,EAAE,iBAAiB,CAAC,WAAW,CAAC,CAAA;KAAE,CAAC,CAAA;IAC9E,wDAAwD;IACxD,0BAA0B,CAAC,EAAE,aAAa,CAAA;IAC1C,6DAA6D;IAC7D,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAA;IAClD,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,+BAA+B,CAgD1E,CAAA"}
1
+ {"version":3,"file":"ConnectAccountsStack.d.ts","sourceRoot":"","sources":["../../../../../src/client/components/connected/ConnectAccountsStack.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAK/C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAA;AAC7D,OAAO,KAAoB,MAAM,OAAO,CAAA;AAiCxC,qEAAqE;AACrE,MAAM,WAAW,+BAAgC,SAAQ,UAAU;IACjE;;;OAGG;IACH,gBAAgB,CAAC,EAAE,aAAa,CAAC;QAAE,OAAO,CAAC,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,UAAU,CAAA;KAAE,CAAC,CAAA;IAC/E,6DAA6D;IAC7D,gBAAgB,CAAC,EAAE,aAAa,CAAC;QAAE,OAAO,CAAC,EAAE,iBAAiB,CAAC,WAAW,CAAC,CAAA;KAAE,CAAC,CAAA;IAC9E,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,aAAa,CAAA;IAChC,wDAAwD;IACxD,0BAA0B,CAAC,EAAE,aAAa,CAAA;IAC1C;;;OAGG;IACH,kBAAkB,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,KAAK,IAAI,CAAA;IAClD;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,KAAK,IAAI,CAAA;IAC7D,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,oBAAoB,EAAE,KAAK,CAAC,EAAE,CAAC,+BAA+B,CA8D1E,CAAA"}
@@ -1,18 +1,51 @@
1
- import type { GatewayName } from '@xyo-network/xl1-sdk';
2
- /** Discovers a wallet gateway and exposes an action that requests account permission from it. */
3
- export declare const useConnectAccount: (gatewayName?: GatewayName, timeout?: number) => {
4
- address: (Lowercase<string> & {
5
- readonly __hex: true;
6
- } & {
7
- readonly __address: true;
8
- }) | undefined;
9
- connectSigner: () => Promise<(Lowercase<string> & {
10
- readonly __hex: true;
11
- } & {
12
- readonly __address: true;
13
- }) | undefined>;
14
- error: Error | undefined;
15
- gateway: import("@xyo-network/xl1-protocol").XyoGatewayRunner | null | undefined;
1
+ import type { Address } from '@ariestools/sdk';
2
+ import type { XyoAddress } from '@xyo-network/sdk';
3
+ import type { GatewayName, XyoGatewayRunner } from '@xyo-network/xl1-sdk';
4
+ /** Wallet connection state and account-access actions returned by {@link useConnectAccount}. */
5
+ export interface ConnectAccountState {
6
+ /**
7
+ * Every account the wallet lets this site use, in grant order. A grant is the
8
+ * set of accounts the site may use, not a selection: let the user choose among
9
+ * them. `[]` means no account is shared (never granted, or revoked);
10
+ * `undefined` means no grant read has succeeded yet or no wallet is present.
11
+ * When a later read fails, the accounts last read are kept and `error` is set.
12
+ */
13
+ accounts?: readonly XyoAddress[];
14
+ /**
15
+ * The first granted account as a hex address, kept for compatibility. It is not
16
+ * the user's choice, and it is `undefined` when the first granted account is not
17
+ * a hex address. Prefer {@link ConnectAccountState.accounts}.
18
+ */
19
+ address?: Address;
20
+ /**
21
+ * Requests account access like {@link ConnectAccountState.requestAccounts}, then
22
+ * resolves with the first granted hex account. Kept for compatibility.
23
+ */
24
+ connectSigner: () => Promise<Address | undefined>;
25
+ /** The first of the wallet discovery, grant read, and account request errors, when present. */
26
+ error?: Error;
27
+ /** Gateway the wallet exposes for the requested network: `undefined` while discovering, `null` when no wallet is present. */
28
+ gateway: XyoGatewayRunner | null | undefined;
29
+ /**
30
+ * Whether wallet discovery or the first grant read is still pending. While it is
31
+ * true an existing grant may not have been read yet, so do not request access.
32
+ */
33
+ isLoading: boolean;
34
+ /** Reads the grant again without prompting; resolves with the granted accounts, or `undefined` when they are unavailable. */
35
+ refreshAccounts: () => Promise<readonly XyoAddress[] | undefined>;
36
+ /**
37
+ * Asks the wallet for account access, which opens its consent prompt where the
38
+ * user may share more accounts, then reads the grant again. Resolves with every
39
+ * granted account, or `undefined` when the request failed (see `error`).
40
+ */
41
+ requestAccounts: () => Promise<readonly XyoAddress[] | undefined>;
42
+ /** Whether wallet discovery finished without finding a wallet. */
16
43
  timedout: boolean;
17
- };
44
+ }
45
+ /**
46
+ * Discovers the wallet, follows this site's account grant, and exposes an action
47
+ * that requests account access. The grant is re-read after each request and when
48
+ * the window regains focus.
49
+ */
50
+ export declare const useConnectAccount: (gatewayName?: GatewayName, timeout?: number) => ConnectAccountState;
18
51
  //# sourceMappingURL=useConnectAccount.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"useConnectAccount.d.ts","sourceRoot":"","sources":["../../../../../../src/client/components/connected/hooks/useConnectAccount.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAcvD,iGAAiG;AACjG,eAAO,MAAM,iBAAiB,GAAI,cAAa,WAA4B,EAAE,UAAU,MAAM;;;;;;;;;;;;;;CAgC5F,CAAA"}
1
+ {"version":3,"file":"useConnectAccount.d.ts","sourceRoot":"","sources":["../../../../../../src/client/components/connected/hooks/useConnectAccount.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAI9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAMzE,gGAAgG;AAChG,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;OAGG;IACH,aAAa,EAAE,MAAM,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAA;IACjD,+FAA+F;IAC/F,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,6HAA6H;IAC7H,OAAO,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,CAAA;IAC5C;;;OAGG;IACH,SAAS,EAAE,OAAO,CAAA;IAClB,6HAA6H;IAC7H,eAAe,EAAE,MAAM,OAAO,CAAC,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC,CAAA;IACjE;;;;OAIG;IACH,eAAe,EAAE,MAAM,OAAO,CAAC,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC,CAAA;IACjE,kEAAkE;IAClE,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,cAAa,WAA4B,EAAE,UAAU,MAAM,KAAG,mBA0C/F,CAAA"}
@@ -1,3 +1,4 @@
1
+ export * from './useGrantedAccounts.ts';
1
2
  export * from './usePermissions.ts';
2
3
  export * from './usePermissionsAccounts.ts';
3
4
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/client/hooks/client/permissions/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,6BAA6B,CAAA"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/client/hooks/client/permissions/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAA;AACvC,cAAc,qBAAqB,CAAA;AACnC,cAAc,6BAA6B,CAAA"}
@@ -0,0 +1,38 @@
1
+ import type { XyoAddress } from '@xyo-network/sdk';
2
+ import type { XyoPermissions } from '@xyo-network/xl1-sdk';
3
+ /** This site's wallet account grant, re-read after account requests and when the window regains focus. */
4
+ export interface GrantedAccountsState {
5
+ /**
6
+ * Every account the wallet lets this site use, in grant order. A grant is the
7
+ * set of accounts the site may use, not a selection. `[]` means no account is
8
+ * shared (never granted, or revoked); `undefined` means the grant is not known
9
+ * because no read has succeeded yet. When a later read fails, the accounts last
10
+ * read are kept and `error` is set.
11
+ */
12
+ accounts?: readonly XyoAddress[];
13
+ /** Error from the most recent grant read, when it failed. */
14
+ error?: Error;
15
+ /** Whether the first grant read for the current permissions provider is still pending. */
16
+ isLoading: boolean;
17
+ /**
18
+ * Reads the grant again. Reading never prompts. Resolves with the accounts read,
19
+ * or `undefined` when there is no permissions provider or the read failed.
20
+ */
21
+ refresh: () => Promise<readonly XyoAddress[] | undefined>;
22
+ /**
23
+ * Asks the wallet for account access, which opens its consent prompt where the
24
+ * user may share more accounts, then reads the grant again. Rejects when the
25
+ * wallet rejects the request or no permissions provider is available.
26
+ */
27
+ request: () => Promise<readonly XyoAddress[] | undefined>;
28
+ }
29
+ /**
30
+ * Follows the wallet's `restrictReturnedAccounts` grant for this site. The grant
31
+ * is read when `permissions` becomes available, again after each
32
+ * {@link GrantedAccountsState.request}, and whenever the window regains focus, so
33
+ * accounts added in the wallet's prompt and access revoked in the wallet are
34
+ * reflected without a remount. When reads overlap, the most recently started
35
+ * read wins.
36
+ */
37
+ export declare function useGrantedAccounts(permissions?: XyoPermissions): GrantedAccountsState;
38
+ //# sourceMappingURL=useGrantedAccounts.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"useGrantedAccounts.d.ts","sourceRoot":"","sources":["../../../../../../src/client/hooks/client/permissions/useGrantedAccounts.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAU1D,0GAA0G;AAC1G,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,UAAU,EAAE,CAAA;IAChC,6DAA6D;IAC7D,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,0FAA0F;IAC1F,SAAS,EAAE,OAAO,CAAA;IAClB;;;OAGG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC,CAAA;IACzD;;;;OAIG;IACH,OAAO,EAAE,MAAM,OAAO,CAAC,SAAS,UAAU,EAAE,GAAG,SAAS,CAAC,CAAA;CAC1D;AA+CD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,CAAC,EAAE,cAAc,GAAG,oBAAoB,CA2CrF"}
@@ -1,3 +1,7 @@
1
- /** Resolves account addresses granted by the wallet's `restrictReturnedAccounts` caveat. */
1
+ /**
2
+ * Resolves account addresses granted by the wallet's `restrictReturnedAccounts` caveat.
3
+ * The grant is read once per permissions provider; use {@link useGrantedAccounts} to
4
+ * follow account requests, revocation, and window focus.
5
+ */
2
6
  export declare const useAccountPermissions: () => [readonly string[] | undefined, Error | undefined, import("@ariestools/sdk-react").UsePromiseState | undefined];
3
7
  //# sourceMappingURL=usePermissionsAccounts.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"usePermissionsAccounts.d.ts","sourceRoot":"","sources":["../../../../../../src/client/hooks/client/permissions/usePermissionsAccounts.ts"],"names":[],"mappings":"AAsBA,4FAA4F;AAC5F,eAAO,MAAM,qBAAqB,uHAejC,CAAA"}
1
+ {"version":3,"file":"usePermissionsAccounts.d.ts","sourceRoot":"","sources":["../../../../../../src/client/hooks/client/permissions/usePermissionsAccounts.ts"],"names":[],"mappings":"AAsBA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,uHAejC,CAAA"}