@solana/kit-plugin-wallet 0.0.0 → 0.13.0

package/src/__typetests__/wallet-typetest.ts

@@ -0,0 +1,129 @@
+import {
+    type ClientWithIdentity,
+    type ClientWithPayer,
+    type ClientWithSubscribeToIdentity,
+    type ClientWithSubscribeToPayer,
+    createClient,
+    TransactionSigner,
+} from '@solana/kit';
+
+import { isWalletWarmingUp, type WalletStatus } from '../index';
+import { ClientWithWallet } from '../types';
+import { walletIdentity, walletPayer, walletSigner, walletWithoutSigner } from '../wallet';
+
+const config = { chain: 'solana:mainnet' as const };
+
+const signer = null as unknown as TransactionSigner;
+
+// [DESCRIBE] walletSigner
+{
+    // It sets payer, identity, and wallet on the client.
+    {
+        const client = createClient().use(walletSigner(config));
+        client.payer satisfies ClientWithPayer['payer'];
+        client.identity satisfies ClientWithIdentity['identity'];
+        client.wallet satisfies ClientWithWallet['wallet'];
+        client.subscribeToPayer satisfies ClientWithSubscribeToPayer['subscribeToPayer'];
+        client.subscribeToIdentity satisfies ClientWithSubscribeToIdentity['subscribeToIdentity'];
+    }
+}
+
+// [DESCRIBE] walletPayer
+{
+    // It sets payer and wallet on the client.
+    {
+        const client = createClient().use(walletPayer(config));
+        client.payer satisfies ClientWithPayer['payer'];
+        client.wallet satisfies ClientWithWallet['wallet'];
+        client.subscribeToPayer satisfies ClientWithSubscribeToPayer['subscribeToPayer'];
+        // @ts-expect-error walletPayer does not install subscribeToIdentity.
+        void client.subscribeToIdentity;
+    }
+    // It does not strip a previously-set identity.
+    {
+        const base = { identity: signer } as unknown as ClientWithIdentity;
+        const result = walletPayer(config)(base);
+        result.identity satisfies TransactionSigner;
+    }
+}
+
+// [DESCRIBE] walletIdentity
+{
+    // It sets identity and wallet on the client.
+    {
+        const client = createClient().use(walletIdentity(config));
+        client.identity satisfies ClientWithIdentity['identity'];
+        client.wallet satisfies ClientWithWallet['wallet'];
+        client.subscribeToIdentity satisfies ClientWithSubscribeToIdentity['subscribeToIdentity'];
+        // @ts-expect-error walletIdentity does not install subscribeToPayer.
+        void client.subscribeToPayer;
+    }
+    // It does not strip a previously-set payer.
+    {
+        const base = { payer: signer } as unknown as ClientWithPayer;
+        const result = walletIdentity(config)(base);
+        result.payer satisfies TransactionSigner;
+    }
+}
+
+// [DESCRIBE] walletWithoutSigner
+{
+    // It sets wallet on the client.
+    {
+        const client = createClient().use(walletWithoutSigner(config));
+        client.wallet satisfies ClientWithWallet['wallet'];
+        // @ts-expect-error walletWithoutSigner does not install subscribeToPayer.
+        void client.subscribeToPayer;
+        // @ts-expect-error walletWithoutSigner does not install subscribeToIdentity.
+        void client.subscribeToIdentity;
+    }
+    // It does not strip a previously-set payer.
+    {
+        const base = { payer: signer } as unknown as ClientWithPayer;
+        const result = walletWithoutSigner(config)(base);
+        result.payer satisfies TransactionSigner;
+    }
+    // It does not strip a previously-set identity.
+    {
+        const base = { identity: signer } as unknown as ClientWithIdentity;
+        const result = walletWithoutSigner(config)(base);
+        result.identity satisfies TransactionSigner;
+    }
+    // It does not strip a previously-set payer and identity.
+    {
+        const base = { identity: signer, payer: signer } as unknown as ClientWithIdentity & ClientWithPayer;
+        const result = walletWithoutSigner(config)(base);
+        result.payer satisfies TransactionSigner;
+        result.identity satisfies TransactionSigner;
+    }
+}
+
+// [DESCRIBE] isWalletWarmingUp
+{
+    // It is exported from the root entry and narrows a status to a boolean.
+    {
+        const status = null as unknown as WalletStatus;
+        isWalletWarmingUp(status) satisfies boolean;
+    }
+    // It requires a WalletStatus argument.
+    {
+        // @ts-expect-error isWalletWarmingUp requires a status argument.
+        isWalletWarmingUp();
+    }
+}
+
+// [DESCRIBE] Only one wallet plugin allowed
+{
+    // It fails to typecheck when a wallet plugin is used on a client that already has wallet.
+    {
+        const client = createClient().use(walletSigner(config));
+        // @ts-expect-error Cannot use a second wallet plugin.
+        walletSigner(config)(client);
+        // @ts-expect-error Cannot use a second wallet plugin.
+        walletPayer(config)(client);
+        // @ts-expect-error Cannot use a second wallet plugin.
+        walletIdentity(config)(client);
+        // @ts-expect-error Cannot use a second wallet plugin.
+        walletWithoutSigner(config)(client);
+    }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './status';
+export * from './types';
+export * from './wallet';

package/src/react/__typetests__/index.ts

@@ -0,0 +1,108 @@
+import type { ReadonlyUint8Array, SignatureBytes } from '@solana/kit';
+import type { SolanaSignInInput, SolanaSignInOutput } from '@solana/wallet-standard-features';
+import type { UiWallet, UiWalletAccount } from '@wallet-standard/ui';
+import type { ReactNode } from 'react';
+
+import type { WalletState, WalletStatus } from '../../types';
+import {
+    useConnect,
+    useConnectedWallet,
+    useDisconnect,
+    useIsWalletReady,
+    useSelectAccount,
+    useSignIn,
+    useSignMessage,
+    useWallets,
+    WalletReadyGate,
+    type WalletReadyGateProps,
+    useWalletStatus,
+} from '../index';
+
+// NB: hooks are only type-checked here, never executed.
+
+// [DESCRIBE] useWalletStatus
+{
+    const status = useWalletStatus();
+    status satisfies WalletStatus;
+}
+
+// [DESCRIBE] useIsWalletReady
+{
+    const isReady = useIsWalletReady();
+    isReady satisfies boolean;
+}
+
+// [DESCRIBE] WalletReadyGate
+{
+    // Both `children` and `fallback` are required `ReactNode` props.
+    ({ children: 'ready', fallback: 'loading' }) satisfies WalletReadyGateProps;
+    // The gate is callable and its return type is assignable to `ReactNode`.
+    const rendered: ReactNode = WalletReadyGate({ children: null, fallback: null });
+    void rendered;
+}
+{
+    // @ts-expect-error `fallback` is required.
+    ({ children: null }) satisfies WalletReadyGateProps;
+}
+
+// [DESCRIBE] useConnectedWallet
+{
+    const connected = useConnectedWallet();
+    connected satisfies WalletState['connected'];
+    // The connection is nullable when disconnected.
+    connected satisfies { account: UiWalletAccount } | null;
+}
+
+// [DESCRIBE] useWallets
+{
+    const wallets = useWallets();
+    wallets satisfies readonly UiWallet[];
+}
+
+// [DESCRIBE] useConnect
+{
+    const action = useConnect();
+    action.dispatch(null as unknown as UiWallet);
+    action.data satisfies readonly UiWalletAccount[] | undefined;
+    // @ts-expect-error dispatch requires the wallet argument.
+    action.dispatch();
+}
+
+// [DESCRIBE] useDisconnect
+{
+    const action = useDisconnect();
+    // The wallet argument is optional — omit it to disconnect the active wallet.
+    action.dispatch();
+    // Or pass a specific wallet to deauthorize.
+    action.dispatch(null as unknown as UiWallet);
+    action.data satisfies void | undefined;
+}
+
+// [DESCRIBE] useSignIn
+{
+    const action = useSignIn();
+    action.dispatch(null as unknown as UiWallet, null as unknown as SolanaSignInInput);
+    action.data satisfies SolanaSignInOutput | undefined;
+    // @ts-expect-error dispatch requires both the wallet and the sign-in input.
+    action.dispatch(null as unknown as UiWallet);
+}
+
+// [DESCRIBE] useSignMessage
+{
+    const action = useSignMessage();
+    action.dispatch(new Uint8Array());
+    action.data satisfies SignatureBytes | undefined;
+}
+{
+    // dispatch accepts a ReadonlyUint8Array (e.g. codec output) without a cast.
+    const action = useSignMessage();
+    action.dispatch(null as unknown as ReadonlyUint8Array);
+}
+
+// [DESCRIBE] useSelectAccount
+{
+    const selectAccount = useSelectAccount();
+    selectAccount(null as unknown as UiWalletAccount) satisfies void;
+    // @ts-expect-error selectAccount requires the account argument.
+    selectAccount();
+}

package/src/react/index.ts

@@ -0,0 +1,301 @@
+import type { ReadonlyUint8Array, SignatureBytes } from '@solana/kit';
+import { type ActionResult, useAction, useClientCapability } from '@solana/react';
+import type { SolanaSignInInput, SolanaSignInOutput } from '@solana/wallet-standard-features';
+import type { UiWallet, UiWalletAccount } from '@wallet-standard/ui';
+import type { ReactNode } from 'react';
+import { useSyncExternalStore } from 'react';
+
+import { isWalletWarmingUp } from '../status';
+import type { ClientWithWallet, WalletNamespace, WalletState, WalletStatus } from '../types';
+
+/**
+ * Reads the wallet namespace from the nearest `ClientProvider`, asserting at mount that a wallet
+ * plugin is installed. Shared by every hook in this module so the capability check, error hook
+ * name, and provider hint stay in one place.
+ */
+function useWalletNamespace(hookName: string): WalletNamespace {
+    return useClientCapability<ClientWithWallet>({
+        capability: 'wallet',
+        hookName,
+        providerHint: 'Install a wallet plugin on the client, e.g. `walletSigner()`.',
+    }).wallet;
+}
+
+// -- State hooks ------------------------------------------------------------
+
+/**
+ * Subscribes to the wallet connection status from a React component.
+ *
+ * Wraps `client.wallet.subscribe` / `getState` with `useSyncExternalStore`, re-rendering only when
+ * the status changes. Requires a `ClientProvider` whose client has a wallet plugin installed;
+ * asserts this at mount with {@link useClientCapability}.
+ *
+ * @returns The current {@link WalletStatus} (`'pending'` on the server and in React Native).
+ *
+ * @example
+ * ```tsx
+ * const status = useWalletStatus();
+ * if (status === 'pending') return null; // avoid flashing UI before auto-reconnect resolves
+ * ```
+ *
+ * @see {@link useConnectedWallet}
+ * @see {@link useWallets}
+ */
+export function useWalletStatus(): WalletStatus {
+    const wallet = useWalletNamespace('useWalletStatus');
+    const getStatus = () => wallet.getState().status;
+    return useSyncExternalStore(wallet.subscribe, getStatus, getStatus);
+}
+
+/**
+ * Subscribes to the active wallet connection from a React component.
+ *
+ * Wraps `client.wallet.subscribe` / `getState` with `useSyncExternalStore`, re-rendering only when
+ * the connection changes (connect, disconnect, or account switch). Requires a `ClientProvider`
+ * whose client has a wallet plugin installed; asserts this at mount with {@link useClientCapability}.
+ *
+ * @returns The active connection — `{ account, signer, wallet }` — or `null` when disconnected.
+ *   `signer` is `null` for read-only wallets.
+ *
+ * @example
+ * ```tsx
+ * const connected = useConnectedWallet();
+ * return connected ? <p>{connected.account.address}</p> : <p>Not connected</p>;
+ * ```
+ *
+ * @see {@link useWalletStatus}
+ * @see {@link useWallets}
+ */
+export function useConnectedWallet(): WalletState['connected'] {
+    const wallet = useWalletNamespace('useConnectedWallet');
+    const getConnected = () => wallet.getState().connected;
+    return useSyncExternalStore(wallet.subscribe, getConnected, getConnected);
+}
+
+/**
+ * Subscribes to the list of discovered wallets from a React component.
+ *
+ * Wraps `client.wallet.subscribe` / `getState` with `useSyncExternalStore`, re-rendering only when
+ * the discovered-wallet list changes. Requires a `ClientProvider` whose client has a wallet plugin
+ * installed; asserts this at mount with {@link useClientCapability}.
+ *
+ * @returns All discovered wallets matching the client's configured chain and filter (empty on the
+ *   server and in React Native).
+ *
+ * @example
+ * ```tsx
+ * const wallets = useWallets();
+ * const connect = useConnect();
+ * return wallets.map(w => <button key={w.name} onClick={() => connect.dispatch(w)}>{w.name}</button>);
+ * ```
+ *
+ * @see {@link useWalletStatus}
+ * @see {@link useConnectedWallet}
+ */
+export function useWallets(): readonly UiWallet[] {
+    const wallet = useWalletNamespace('useWallets');
+    const getWallets = () => wallet.getState().wallets;
+    return useSyncExternalStore(wallet.subscribe, getWallets, getWallets);
+}
+
+/**
+ * Reports whether the wallet client has finished its initial auto-reconnect "warm-up".
+ *
+ * Returns `false` while the status is `'pending'` or `'reconnecting'` — the transient states a
+ * freshly built client passes through while it silently re-establishes a persisted connection — and
+ * `true` once it settles into any stable state (`'connected'`, `'disconnected'`, or a user-initiated
+ * `'connecting'` / `'disconnecting'`). This is the declarative, render-time counterpart to the
+ * store's imperative `whenReady()`, gating on the exact same set of statuses.
+ *
+ * Use it to hold back wallet-dependent UI until the connection has settled, so a persisted wallet
+ * never flashes "disconnected" before it reconnects. Re-renders only when this readiness boolean
+ * flips, not on every status change. Requires a `ClientProvider` whose client has a wallet plugin
+ * installed; asserts this at mount with {@link useClientCapability}.
+ *
+ * @returns `true` once the warm-up has settled, otherwise `false`.
+ *
+ * @example
+ * ```tsx
+ * const isReady = useIsWalletReady();
+ * return <button disabled={!isReady}>Connect</button>;
+ * ```
+ *
+ * @see {@link WalletReadyGate}
+ * @see {@link useWalletStatus}
+ */
+export function useIsWalletReady(): boolean {
+    const wallet = useWalletNamespace('useIsWalletReady');
+    const getIsReady = () => !isWalletWarmingUp(wallet.getState().status);
+    return useSyncExternalStore(wallet.subscribe, getIsReady, getIsReady);
+}
+
+// -- Action hooks -----------------------------------------------------------
+
+/**
+ * Connects to a wallet from a React component.
+ *
+ * Wraps `client.wallet.connect` with {@link useAction}. Requires a `ClientProvider` whose client
+ * has a wallet plugin installed; asserts this at mount with {@link useClientCapability}. An
+ * in-flight connect is superseded when a newer one is dispatched.
+ *
+ * `dispatch`/`dispatchAsync` take the {@link UiWallet} to connect to and resolve with the wallet's
+ * accounts once connected.
+ *
+ * @example
+ * ```tsx
+ * const { dispatch, isRunning } = useConnect();
+ * <button disabled={isRunning} onClick={() => dispatch(wallet)}>Connect</button>
+ * ```
+ *
+ * @see {@link useDisconnect}
+ * @see {@link useSignIn}
+ */
+export function useConnect(): ActionResult<[wallet: UiWallet], readonly UiWalletAccount[]> {
+    const wallet = useWalletNamespace('useConnect');
+    return useAction((abortSignal, uiWallet: UiWallet) => wallet.connect(uiWallet, { abortSignal }));
+}
+
+/**
+ * Disconnects a wallet from a React component.
+ *
+ * Wraps `client.wallet.disconnect` with {@link useAction}. Requires a `ClientProvider` whose client
+ * has a wallet plugin installed; asserts this at mount with {@link useClientCapability}.
+ *
+ * `dispatch`/`dispatchAsync` take an optional {@link UiWallet}. Called with no argument they
+ * disconnect the active wallet; passing a non-active, currently authorized wallet deauthorizes that
+ * wallet while leaving the active connection in place.
+ *
+ * @example
+ * ```tsx
+ * const { dispatch, isRunning } = useDisconnect();
+ * // Disconnect the active wallet:
+ * <button disabled={isRunning} onClick={() => dispatch()}>Disconnect</button>
+ * // Or deauthorize a specific wallet:
+ * <button disabled={isRunning} onClick={() => dispatch(wallet)}>Forget this wallet</button>
+ * ```
+ *
+ * @see {@link useConnect}
+ */
+export function useDisconnect(): ActionResult<[wallet?: UiWallet], void> {
+    const wallet = useWalletNamespace('useDisconnect');
+    return useAction((abortSignal, uiWallet?: UiWallet) => wallet.disconnect(uiWallet, { abortSignal }));
+}
+
+/**
+ * Signs in with a wallet (Sign In With Solana) from a React component.
+ *
+ * Wraps `client.wallet.signIn` with {@link useAction}. Requires a `ClientProvider` whose client has
+ * a wallet plugin installed; asserts this at mount with {@link useClientCapability}. Like
+ * {@link useConnect}, this establishes a full connection. An in-flight connect is superseded when a
+ * newer one is dispatched.
+ *
+ * `dispatch`/`dispatchAsync` take the {@link UiWallet} and a `SolanaSignInInput` (pass `{}` for no
+ * customization) and resolve with the wallet's sign-in output.
+ *
+ * @example
+ * ```tsx
+ * const { dispatch } = useSignIn();
+ * dispatch(wallet, { domain: window.location.host });
+ * ```
+ *
+ * @see {@link useConnect}
+ */
+export function useSignIn(): ActionResult<[wallet: UiWallet, input: SolanaSignInInput], SolanaSignInOutput> {
+    const wallet = useWalletNamespace('useSignIn');
+    return useAction((abortSignal, uiWallet: UiWallet, input: SolanaSignInInput) =>
+        wallet.signIn(uiWallet, input, { abortSignal }),
+    );
+}
+
+/**
+ * Signs an arbitrary message with the connected account from a React component.
+ *
+ * Wraps `client.wallet.signMessage` with {@link useAction}. Requires a `ClientProvider` whose
+ * client has a wallet plugin installed; asserts this at mount with {@link useClientCapability}.
+ * A stale in-flight dispatch is dropped from the hook's state when a newer one starts (though
+ * the wallet may still complete the older request in the background).
+ *
+ * `dispatch`/`dispatchAsync` take the message bytes and resolve with the signature. The bytes are
+ * only read, never mutated, so a {@link ReadonlyUint8Array} (e.g. the output of a `@solana/kit`
+ * codec) is accepted directly without a cast.
+ *
+ * @example
+ * ```tsx
+ * const { dispatch } = useSignMessage();
+ * dispatch(new TextEncoder().encode('Hello'));
+ * ```
+ */
+export function useSignMessage(): ActionResult<[message: ReadonlyUint8Array], SignatureBytes> {
+    const wallet = useWalletNamespace('useSignMessage');
+    return useAction((abortSignal, message: ReadonlyUint8Array) => wallet.signMessage(message, { abortSignal }));
+}
+
+/**
+ * Returns a callback that selects a wallet account.
+ *
+ * Requires a `ClientProvider` whose client has a wallet plugin installed; asserts this at mount
+ * with {@link useClientCapability}. Unlike the other action hooks, `selectAccount` is synchronous —
+ * this hook returns the bound function directly rather than an `ActionResult`.
+ *
+ * The account may belong to any currently authorized wallet, not only the active one. Selecting an
+ * account from a different authorized wallet switches the active connection to that wallet
+ * synchronously (no prompt), leaving the previously active wallet authorized.
+ *
+ * @returns The `selectAccount` function — call it with a {@link UiWalletAccount} belonging to any
+ *   currently authorized wallet. It throws if the account's handle can't be resolved to an
+ *   authorized wallet (or isn't among that wallet's accounts), or that wallet is currently
+ *   disconnecting.
+ *
+ * @example
+ * ```tsx
+ * const selectAccount = useSelectAccount();
+ * <button onClick={() => selectAccount(account)}>Use this account</button>
+ * ```
+ *
+ * @see {@link useConnectedWallet}
+ */
+export function useSelectAccount(): WalletNamespace['selectAccount'] {
+    return useWalletNamespace('useSelectAccount').selectAccount;
+}
+
+// -- Components -------------------------------------------------------------
+
+/**
+ * Props for {@link WalletReadyGate}.
+ */
+export type WalletReadyGateProps = Readonly<{
+    /** Rendered once the wallet client has finished its initial auto-reconnect warm-up. */
+    children: ReactNode;
+    /** Rendered while the client is still warming up (`'pending'` / `'reconnecting'`). */
+    fallback: ReactNode;
+}>;
+
+/**
+ * Renders `fallback` while the wallet client is still in its initial auto-reconnect warm-up
+ * (`'pending'` / `'reconnecting'`), then reveals `children` once the connection has settled.
+ *
+ * A declarative wrapper over {@link useIsWalletReady} for the common case of holding back a whole
+ * wallet-dependent subtree. Its props are shaped like React's `<Suspense fallback>`, but it is
+ * synchronous — it renders `fallback` directly off the reactive status rather than suspending, so it
+ * needs no `<Suspense>` ancestor. It lets an app paint its chrome immediately while gating only the
+ * wallet-dependent UI, so a persisted wallet never flashes "disconnected" before it silently
+ * reconnects. For finer control (disabling a button, showing an inline spinner) read the boolean from
+ * {@link useIsWalletReady} directly. To actually suspend a subtree instead, throw the Suspense-safe
+ * {@link WalletNamespace.whenReady} promise from your own component.
+ *
+ * Requires a `ClientProvider` whose client has a wallet plugin installed; asserts this at mount with
+ * {@link useClientCapability}.
+ *
+ * @example
+ * ```tsx
+ * <WalletReadyGate fallback={<Spinner />}>
+ *     <WalletDependentApp />
+ * </WalletReadyGate>
+ * ```
+ *
+ * @see {@link useIsWalletReady}
+ * @see {@link useWalletStatus}
+ */
+export function WalletReadyGate({ children, fallback }: WalletReadyGateProps): ReactNode {
+    return useIsWalletReady() ? children : fallback;
+}

package/src/status.ts

@@ -0,0 +1,33 @@
+import type { WalletStatus } from './types';
+
+/**
+ * Reports whether a {@link WalletStatus} belongs to the initial auto-reconnect
+ * "warm-up": `'pending'` (before auto-reconnect has resolved) and
+ * `'reconnecting'` (silently re-establishing a persisted connection). During
+ * this window a persisted wallet is on its way back, so wallet-dependent UI
+ * should usually hold rather than flash a "disconnected" state.
+ *
+ * User-initiated `'connecting'` / `'disconnecting'` are deliberately excluded —
+ * a normal connect or disconnect is not a warm-up and must stay interactive.
+ *
+ * This is the single source of truth for "warm-up" across the plugin: the
+ * store's {@link WalletNamespace.whenReady} waits for the status to leave this set, and the
+ * React `useIsWalletReady` hook and `WalletReadyGate` component gate on its
+ * negation. Use it directly to gate on warm-up from a non-React consumer.
+ *
+ * @param status - A status from `client.wallet.getState().status`.
+ * @returns `true` while the client is warming up, otherwise `false`.
+ *
+ * @example
+ * ```ts
+ * client.wallet.subscribe(() => {
+ *     const { status } = client.wallet.getState();
+ *     setLoading(isWalletWarmingUp(status));
+ * });
+ * ```
+ *
+ * @see {@link WalletNamespace.whenReady} — the imperative (promise-based) counterpart.
+ */
+export function isWalletWarmingUp(status: WalletStatus): boolean {
+    return status === 'pending' || status === 'reconnecting';
+}