Add basic documentation, clean up code (#9)

* wip: docs

* remove 05-patterns as it is not correct

* move docs

* clean up wallet adpater compat provider

* docs(changeset): Remove debug logs from wallet-adapter-compat

* more docs updates, clean up code

Author: macalinao

.changeset/warm-mirrors-throw.md

@@ -0,0 +1,5 @@
+---
+"@macalinao/wallet-adapter-compat": patch
+---
+
+Remove debug logs from wallet-adapter-compat

README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@macalinao/grill.svg)](https://www.npmjs.com/package/@macalinao/grill)
 
-A comprehensive toolkit for building Solana applications with React, featuring automatic account batching and caching.
+A comprehensive toolkit for building Solana applications with React, featuring automatic account batching, type-safe account decoding, and seamless transaction management. Built on top of [gill](https://github.com/DecalLabs/gill) and [@solana/kit](https://github.com/anza-xyz/kit).
 
 ## Packages
 
@@ -38,25 +38,35 @@ bun add @macalinao/dataloader-es
 
 ```tsx
 import { GrillProvider } from "@macalinao/grill";
+import { WalletAdapterCompatProvider } from "@macalinao/wallet-adapter-compat";
 import { createSolanaClient } from "gill";
 import { SolanaProvider } from "gill-react";
 import { ConnectionProvider, WalletProvider } from "@solana/wallet-adapter-react";
 import { WalletModalProvider } from "@solana/wallet-adapter-react-ui";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { Toaster } from "sonner";
 
 const queryClient = new QueryClient();
 const solanaClient = createSolanaClient({ urlOrMoniker: "mainnet-beta" });
 
 function App() {
+  const wallets = useMemo(
+    () => [new PhantomWalletAdapter(), new SolflareWalletAdapter()],
+    []
+  );
+
   return (
     <QueryClientProvider client={queryClient}>
       <SolanaProvider client={solanaClient}>
         <ConnectionProvider endpoint="https://api.mainnet-beta.solana.com">
-          <WalletProvider wallets={[]} autoConnect>
+          <WalletProvider wallets={wallets} autoConnect>
             <WalletModalProvider>
-              <GrillProvider>
-                {/* Your app components */}
-              </GrillProvider>
+              <WalletAdapterCompatProvider>
+                <GrillProvider>
+                  {/* Your app components */}
+                  <Toaster position="bottom-right" />
+                </GrillProvider>
+              </WalletAdapterCompatProvider>
             </WalletModalProvider>
           </WalletProvider>
         </ConnectionProvider>
@@ -66,45 +76,95 @@ function App() {
 }
 ```
 
-## Using Grill
+## Core Features
+
+### 🎯 Automatic Account Batching
+
+Multiple account requests are automatically batched into single RPC calls:
 
 ```tsx
-import { useAccount } from "@macalinao/grill";
+import { useAccount, useAssociatedTokenAccount } from "@macalinao/grill";
+
+function Dashboard() {
+  // All these requests are batched into 1 RPC call!
+  const { data: userAccount } = useAccount({ 
+    address: userAddress 
+  });
+  
+  const { data: usdcAccount } = useAssociatedTokenAccount({
+    mint: USDC_MINT,
+    owner: userAddress
+  });
+  
+  const { data: solAccount } = useAccount({ 
+    address: poolAddress 
+  });
+}
+```
 
-function MyComponent() {
-  const { data: account, isLoading, error } = useAccount('So11111111111111111111111111111111111111112');
+### 🔄 Simple Transaction Management
 
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-  if (!account) return <div>Account not found</div>;
+Send transactions with automatic status notifications:
 
-  return (
-    <div>
-      <p>Owner: {account.owner}</p>
-      <p>Lamports: {account.lamports}</p>
-    </div>
-  );
+```tsx
+import { useSendTX, useKitWallet } from "@macalinao/grill";
+
+function SwapButton() {
+  const { signer } = useKitWallet();
+  const sendTX = useSendTX();
+  
+  const handleSwap = async () => {
+    const instructions = buildSwapInstructions();
+    await sendTX("Swap USDC for SOL", instructions);
+    // Automatic toast notifications for each stage!
+  };
+  
+  return <button onClick={handleSwap}>Swap</button>;
 }
 ```
 
-## Features
+### 📖 Type-Safe Account Decoding
+
+```tsx
+import { useAccount } from "@macalinao/grill";
+import { getTokenAccountDecoder } from "@solana-program/token";
+
+function TokenBalance({ tokenAccountAddress }) {
+  const { data: account } = useAccount({
+    address: tokenAccountAddress,
+    decoder: getTokenAccountDecoder()
+  });
+  
+  // account.data is fully typed as TokenAccount!
+  return <div>Balance: {account?.data.amount.toString()}</div>;
+}
+```
+
+## Why Grill?
+
+Traditional Solana development suffers from the N+1 query problem. Every component that needs account data makes its own RPC request. Grill solves this with automatic batching using the DataLoader pattern from GraphQL.
+
+**Without Grill:** 10 components = 10 RPC calls = Rate limiting & slow UX  
+**With Grill:** 10 components = 1 batched RPC call = Fast & efficient
+
+## Key Benefits
 
-- 🚀 Built on gill and gill-react for modern Solana development
-- ⚡ Automatic account batching - multiple concurrent requests are batched into single RPC calls
-- 📊 React Query integration for caching and state management
-- 🔐 Seamless wallet adapter integration
-- 🎯 Type-safe with full TypeScript support
-- 📦 Modern ESM package structure
+- ⚡ **10x fewer RPC calls** through automatic batching
+- 🎯 **Type-safe everything** - accounts, transactions, PDAs
+- 🔄 **Automatic cache management** with React Query
+- 🎨 **Beautiful transaction UX** with toast notifications
+- 🏗️ **Incremental migration** - works alongside existing code
+- 📦 **Modern stack** - Built on @solana/kit and gill
 
-## Architecture
+## Documentation
 
-Grill provides a `GrillProvider` that creates a DataLoader for batching account requests. When multiple components request account data simultaneously, Grill automatically batches these requests into a single RPC call, significantly improving performance.
+Check out the comprehensive guides in [`docs/grill/`](./docs/grill/):
 
-The `useAccount` hook integrates with React Query to provide:
-- Automatic caching with configurable stale times
-- Background refetching
-- Loading and error states
-- Manual refetch capabilities
+1. [**Introduction**](./docs/grill/01-intro.md) - Why Grill and the core concepts
+2. [**Setup & Migration**](./docs/grill/02-setup.md) - Installation and incremental migration
+3. [**Reading Accounts**](./docs/grill/03-accounts.md) - Efficient account fetching with batching
+4. [**Making Transactions**](./docs/grill/04-transactions.md) - Clean transaction management
+5. [**Advanced Patterns**](./docs/grill/05-patterns.md) - Production patterns and best practices
 
 ## Development
 

apps/example-dapp/src/App.tsx

@@ -12,7 +12,9 @@ import {
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
 import { createRouter, RouterProvider } from "@tanstack/react-router";
+import { createSolanaClient } from "gill";
 import { SolanaProvider } from "gill-react";
+import type * as React from "react";
 import { useMemo } from "react";
 import { Toaster } from "sonner";
 
@@ -30,7 +32,6 @@ declare module "@tanstack/react-router" {
 }
 
 import "@solana/wallet-adapter-react-ui/styles.css";
-import { createSolanaClient } from "gill";
 
 console.log(import.meta.env);
 console.log(import.meta.env.VITE_SOLANA_RPC_URL ?? "mainnet-beta");

apps/example-dapp/src/components/SimpleDashboard.tsx

@@ -1,6 +1,7 @@
 import { useAccount, useKitWallet } from "@macalinao/grill";
 import { WalletMultiButton } from "@solana/wallet-adapter-react-ui";
 import { useSolanaClient } from "gill-react";
+import type * as React from "react";
 import { useState } from "react";
 import { toast } from "sonner";
 import { Button } from "@/components/ui/button";
@@ -12,15 +13,15 @@ import {
   CardTitle,
 } from "@/components/ui/card";
 
-export function SimpleDashboard() {
+export const SimpleDashboard: React.FC = () => {
   const { signer } = useKitWallet();
   const { rpc } = useSolanaClient();
   // Only fetch account if signer is available
   const accountQuery = useAccount({ address: signer ? signer.address : null });
   const [slot, setSlot] = useState<number | null>(null);
   const [loading, setLoading] = useState(false);
 
-  const handleRefreshBalance = () => {
+  const handleRefreshBalance = (): void => {
     if (!signer) {
       toast.error("Please connect your wallet first");
       return;
@@ -30,7 +31,7 @@ export function SimpleDashboard() {
     toast.success("Balance refreshed");
   };
 
-  const handleGetSlot = async () => {
+  const handleGetSlot = async (): Promise<void> => {
     setLoading(true);
     try {
       const currentSlot = await rpc.getSlot().send();
@@ -122,4 +123,4 @@ export function SimpleDashboard() {
       </div>
     </div>
   );
-}
+};

apps/example-dapp/src/components/layout/examples/index.tsx

@@ -1,6 +1,6 @@
 import { Link, Outlet, useLocation } from "@tanstack/react-router";
 import { Coins, LayoutDashboard } from "lucide-react";
-import type { FC } from "react";
+import type * as React from "react";
 import {
   Sidebar,
   SidebarContent,
@@ -40,7 +40,9 @@ const exampleNavItems: ExampleNavItem[] = [
   },
 ];
 
-export const ExamplesLayout: FC<ExamplesLayoutProps> = ({ className }) => {
+export const ExamplesLayout: React.FC<ExamplesLayoutProps> = ({
+  className,
+}) => {
   const location = useLocation();
 
   return (

apps/example-dapp/src/components/layout/main/index.tsx

@@ -1,6 +1,6 @@
 import { WalletMultiButton } from "@solana/wallet-adapter-react-ui";
 import { Link, Outlet } from "@tanstack/react-router";
-import type { FC } from "react";
+import type * as React from "react";
 import { ThemeToggle } from "@/components/theme-toggle";
 import {
   NavigationMenu,
@@ -14,7 +14,7 @@ export interface MainLayoutProps {
   className?: string;
 }
 
-export const MainLayout: FC<MainLayoutProps> = ({ className }) => {
+export const MainLayout: React.FC<MainLayoutProps> = ({ className }) => {
   return (
     <div className={cn("flex min-h-screen flex-col bg-background", className)}>
       <header className="fixed top-0 z-50 flex h-16 w-full border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">

apps/example-dapp/src/components/theme-provider.tsx

@@ -1,3 +1,4 @@
+import type * as React from "react";
 import { createContext, useContext, useEffect, useState } from "react";
 
 type Theme = "dark" | "light" | "system";
@@ -20,12 +21,12 @@ const initialState: ThemeProviderState = {
 
 const ThemeProviderContext = createContext<ThemeProviderState>(initialState);
 
-export function ThemeProvider({
+export const ThemeProvider: React.FC<ThemeProviderProps> = ({
   children,
   defaultTheme = "system",
   storageKey = "vite-ui-theme",
   ...props
-}: ThemeProviderProps) {
+}) => {
   const [theme, setTheme] = useState<Theme>(
     () => (localStorage.getItem(storageKey) ?? defaultTheme) as Theme,
   );
@@ -61,10 +62,10 @@ export function ThemeProvider({
       {children}
     </ThemeProviderContext.Provider>
   );
-}
+};
 
 // eslint-disable-next-line react-refresh/only-export-components
-export const useTheme = () => {
+export const useTheme = (): ThemeProviderState => {
   const context = useContext(ThemeProviderContext);
   return context;
 };

apps/example-dapp/src/components/theme-toggle.tsx

@@ -1,8 +1,9 @@
 import { Moon, Sun } from "lucide-react";
+import type * as React from "react";
 import { useTheme } from "@/components/theme-provider";
 import { Button } from "@/components/ui/button";
 
-export function ThemeToggle() {
+export const ThemeToggle: React.FC = () => {
   const { theme, setTheme } = useTheme();
 
   return (
@@ -18,4 +19,4 @@ export function ThemeToggle() {
       <span className="sr-only">Toggle theme</span>
     </Button>
   );
-}
+};

apps/example-dapp/src/components/ui/input-token-amount.tsx

@@ -1,4 +1,4 @@
-import type { FC } from "react";
+import type * as React from "react";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { cn } from "@/lib/utils";
@@ -14,7 +14,7 @@ export interface InputTokenAmountProps {
   disabled?: boolean;
 }
 
-export const InputTokenAmount: FC<InputTokenAmountProps> = ({
+export const InputTokenAmount: React.FC<InputTokenAmountProps> = ({
   token,
   value,
   onChange,

apps/example-dapp/src/routes/__root.tsx

@@ -1,12 +1,15 @@
 import { createRootRoute } from "@tanstack/react-router";
 import { TanStackRouterDevtools } from "@tanstack/react-router-devtools";
+import type * as React from "react";
 import { MainLayout } from "@/components/layout/main";
 
+const RootComponent: React.FC = () => (
+  <>
+    <MainLayout />
+    <TanStackRouterDevtools position="bottom-left" />
+  </>
+);
+
 export const Route = createRootRoute({
-  component: () => (
-    <>
-      <MainLayout />
-      <TanStackRouterDevtools position="bottom-left" />
-    </>
-  ),
+  component: RootComponent,
 });