@solana/react-hooks 0.0.0 → 0.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @solana/react-hooks
 
-React hooks for `@solana/client-core`. Drop in the provider and call hooks instead of juggling RPC
+React hooks for `@solana/client`. Drop in the provider and call hooks instead of juggling RPC
 clients, wallets, and stores yourself.
 
 > **Status:** Experimental – breaking changes may land often.
@@ -59,6 +59,8 @@ export function App() {
 - `useBalance` / `useAccount` – fetch lamports once or keep account data in sync.
 - `useSolTransfer`, `useSplToken`, `useTransactionPool` – helper-driven flows for SOL, SPL, and
   general transactions.
+- `useSendTransaction` – prepare and submit arbitrary instructions with shared mutation state.
+- `useSignatureStatus`, `useWaitForSignature` – declarative helpers for tracking confirmations.
 - `useClientStore` – access the underlying Zustand store if you need low-level state.
 
 ### Wallet helpers
@@ -178,7 +180,7 @@ const SplBalance = ({ mint }) => {
 Compose instructions, refresh blockhashes automatically, and send transactions from one hook.
 
 ```tsx
-import type { TransactionInstructionInput } from '@solana/client-core';
+import type { TransactionInstructionInput } from '@solana/client';
 
 const useMemoizedInstruction = (): TransactionInstructionInput => ({
     accounts: [],
@@ -220,48 +222,136 @@ function ClusterStatus() {
 }
 ```
 
+### General transaction sender
+
+Use `useSendTransaction` when you already have instructions/messages and just need a mutation helper
+that exposes `{ send, sendPrepared, status, error, signature }`. When no authority is supplied, it
+will use the currently connected wallet session by default.
+
+```tsx
+import { useSendTransaction } from '@solana/react-hooks';
+
+function SendAnythingButton({ instructions }) {
+    const { send, isSending, signature, error } = useSendTransaction();
+
+    return (
+        <div>
+            <button disabled={isSending} onClick={() => send({ instructions })}>
+                {isSending ? 'Submitting…' : 'Send transaction'}
+            </button>
+            {signature ? <p>Signature: {signature}</p> : null}
+            {error ? <p role="alert">Failed to send: {String(error)}</p> : null}
+        </div>
+    );
+}
+```
+
+### Signature helpers
+
+Poll RPC for signature metadata or wait for a confirmation level without writing loops.
+
+```tsx
+import { useSignatureStatus, useWaitForSignature } from '@solana/react-hooks';
+
+function SignatureStatusCard({ signature }) {
+    const status = useSignatureStatus(signature);
+
+    if (status.isLoading) return <p>Loading…</p>;
+    if (status.isError) return <p>RPC error.</p>;
+
+    return (
+        <div>
+            <p>Confirmation: {status.confirmationStatus ?? 'pending'}</p>
+            <button onClick={() => status.refresh()}>Refresh</button>
+        </div>
+    );
+}
+
+function WaitForSignature({ signature }) {
+    const wait = useWaitForSignature(signature, { commitment: 'finalized' });
+
+    if (wait.waitStatus === 'error') return <p role="alert">Failed: {JSON.stringify(wait.waitError)}</p>;
+    if (wait.waitStatus === 'success') return <p>Finalized!</p>;
+    if (wait.waitStatus === 'waiting') return <p>Waiting for confirmation…</p>;
+    return <p>Provide a signature</p>;
+}
+```
+
 ## Query hooks
 
 Wrap a subtree with `<SolanaQueryProvider>` and call hooks like `useLatestBlockhash`,
-`useProgramAccounts`, or `useSimulateTransaction`. Every hook returns `{ data, status, refresh }` so
-you can read the current value and trigger a refetch:
+`useProgramAccounts`, `useSignatureStatus`, or `useSimulateTransaction`. Every hook returns
+`{ data, status, refresh }` so you can read the current value and trigger a refetch. Want to lean on React
+Suspense later? Pass `suspense` to `SolanaQueryProvider` and wrap just the section that should pause in a
+local `<Suspense>` boundary—no hook changes required:
+
+```tsx
+import { SolanaQueryProvider, useBalance } from '@solana/react-hooks';
+import { Suspense } from 'react';
+
+function BalanceDetails({ address }: { address: string }) {
+    const balance = useBalance(address);
+    return <p>Lamports: {balance.lamports?.toString() ?? '0'}</p>;
+}
+
+export function WalletPanel({ address }: { address: string }) {
+    return (
+        <SolanaQueryProvider suspense>
+            {/* Only this block suspends while balance loads */}
+            <Suspense fallback={<p>Loading balance…</p>}>
+                <BalanceDetails address={address} />
+            </Suspense>
+        </SolanaQueryProvider>
+    );
+}
+```
 
 ### Latest blockhash
 
 Poll or refetch the cluster's latest blockhash.
 
 ```tsx
-import { useLatestBlockhash } from '@solana/react-hooks';
+import { SolanaQueryProvider, useLatestBlockhash } from '@solana/react-hooks';
 
 function BlockhashTicker() {
-    const { blockhash, status, refresh } = useLatestBlockhash({ refreshInterval: 20_000 });
+    const latest = useLatestBlockhash({ refreshInterval: 20_000 });
+    if (latest.status === 'loading') return <p>Fetching blockhash…</p>;
+    if (latest.status === 'error') return <p role="alert">Failed to fetch blockhash.</p>;
 
     return (
         <div>
-            <button onClick={() => refresh()}>Refresh</button>
-            <p>Status: {status}</p>
-            <p>Blockhash: {blockhash ?? 'loading…'}</p>
+            <button onClick={() => latest.refresh()}>Refresh</button>
+            <p>Status: {latest.status}</p>
+            <p>Blockhash: {latest.blockhash ?? 'unknown'}</p>
         </div>
     );
 }
+
+export function BlockhashCard() {
+    return (
+        <SolanaQueryProvider>
+            <BlockhashTicker />
+        </SolanaQueryProvider>
+    );
+}
 ```
 
 ### Program accounts
 
 ```tsx
-import { SolanaQueryProvider, useProgramAccounts } from '@solana/react-hooks';
+import { SolanaClientProvider, SolanaQueryProvider, useProgramAccounts } from '@solana/react-hooks';
 
 function ProgramAccountsList({ programAddress }) {
-    const { data, status, refresh } = useProgramAccounts(programAddress);
-
-    if (status === 'loading') return <p>Loading…</p>;
-    if (status === 'error') return <p>Retry later.</p>;
+    const query = useProgramAccounts(programAddress);
+    if (query.status === 'loading') return <p>Loading accounts…</p>;
+    if (query.status === 'error') return <p role="alert">Retry later.</p>;
 
     return (
         <div>
-            <button onClick={() => refresh()}>Refresh</button>
+            <button onClick={() => query.refresh()}>Refresh</button>
+            <p>Status: {query.status}</p>
             <ul>
-                {data?.map(({ pubkey }) => (
+                {query.accounts?.map(({ pubkey }) => (
                     <li key={pubkey.toString()}>{pubkey.toString()}</li>
                 ))}
             </ul>
@@ -288,15 +378,14 @@ Simulate any transaction payload (wire string or object) and read RPC logs.
 import { useSimulateTransaction } from '@solana/react-hooks';
 
 function SimulationLogs({ transaction }) {
-    const { logs, status, refresh } = useSimulateTransaction(transaction);
-
-    if (status === 'loading') return <p>Simulating…</p>;
-    if (status === 'error') return <p>Simulation failed.</p>;
-
+    const query = useSimulateTransaction(transaction);
+    if (query.status === 'loading') return <p>Simulating…</p>;
+    if (query.status === 'error') return <p role="alert">Simulation failed.</p>;
     return (
         <div>
-            <button onClick={() => refresh()}>Re-run</button>
-            <pre>{JSON.stringify(logs ?? [], null, 2)}</pre>
+            <button onClick={() => query.refresh()}>Re-run</button>
+            <p>Status: {query.status}</p>
+            <pre>{JSON.stringify(query.logs, null, 2)}</pre>
         </div>
     );
 }
@@ -306,8 +395,8 @@ function SimulationLogs({ transaction }) {
 
 - Need Wallet Standard buttons or sign/send helpers? Use `useSignIn`, `useSignMessage`,
   `useSignTransaction`, and friends from `walletStandardHooks.ts`.
-- Looking for examples? See `examples/react-hooks` for a ready-to-run playground that wires the
-  provider, hooks, and mock UIs together.
+- Looking for examples? See `examples/react-hooks` for a ready-to-run, tabbed playground that wires
+  the provider, hooks, and mock UIs together across wallet/state, transaction, and query demos.
 
 ## Scripts