shogun-button-react 1.10.2 → 1.11.0

package/README.md

@@ -1,19 +1,21 @@
 # Shogun Button React
 
-A React component library for seamless integration of Shogun authentication into your applications. This library provides a simple yet powerful way to add Shogun authentication to your React applications.
+A comprehensive React component library for seamless integration of Shogun authentication into your applications. This library provides a simple yet powerful way to add multi-method authentication, account management, and real-time data synchronization to your React applications.
 
-## Features
+## ✨ Features
 
-- 🚀 Easy to integrate
-- 🎨 Customizable UI components
-- 🔒 Secure authentication flow
-- 🌓 Dark mode support
-- 🔌 Multiple authentication methods (Username/Password, MetaMask, WebAuthn, Nostr, OAuth)
-- 🔑 Account backup and recovery (Gun pair export/import)
-- 📱 Responsive design
-- 🌍 TypeScript support
+- 🚀 **Easy Integration** - Simple setup with minimal configuration
+- 🎨 **Customizable UI** - Modern, responsive design with dark mode support
+- 🔒 **Multi-Authentication** - Support for Password, MetaMask, WebAuthn, Nostr, and OAuth
+- 🔑 **Account Management** - Export/import Gun pairs for account backup and recovery
+- 📱 **Responsive Design** - Works seamlessly across all device sizes
+- 🌍 **TypeScript Support** - Full type safety and IntelliSense support
+- 🔌 **Plugin System** - Advanced Gun operations with custom hooks
+- 📊 **Real-time Data** - Reactive data synchronization with RxJS observables
 
-## Installation
+## 🚀 Quick Start
+
+### Installation
 
 ```bash
 npm install shogun-button-react
@@ -21,61 +23,47 @@ npm install shogun-button-react
 yarn add shogun-button-react
 ```
 
-## Quick Start
+### Basic Usage
 
 ```tsx
 import React from "react";
-import {
-  ShogunButton,
-  ShogunButtonProvider,
-  shogunConnector,
-} from "shogun-button-react";
+import { ShogunButton, ShogunButtonProvider, shogunConnector } from "shogun-button-react";
 import "shogun-button-react/styles.css";
 
 function App() {
-  const { sdk, options } = shogunConnector({
-    appName: "My App",
-    appDescription: "An awesome app with Shogun authentication",
-    appUrl: "https://myapp.com",
-    appIcon: "https://myapp.com/icon.png",
-    // Enable authentication methods
+  const { core, options } = shogunConnector({
+    appName: "My Awesome App",
+    // Enable specific authentication methods
     showMetamask: true,
     showWebauthn: true,
     showNostr: true,
     showOauth: true,
-    // Network configuration
-    peers: ["https://gun-manhattan.herokuapp.com/gun"],
-    // OAuth providers (optional)
-    oauth: {
-      providers: {
-        google: {
-          clientId: "YOUR_GOOGLE_CLIENT_ID",
-          redirectUri: "http://localhost:3000/auth/callback",
-        },
-      },
-    },
+    // Optional peers
+    peers: [
+      "https://gun-manhattan.herokuapp.com/gun"
+    ],
   });
 
   return (
     <ShogunButtonProvider
-      sdk={sdk}
+      core={core}
       options={options}
       onLoginSuccess={(data) => {
         console.log("Login successful!", data);
       }}
       onSignupSuccess={(data) => {
-        console.log("Signup successful!", data);
+        console.log("Account created successfully!", data);
       }}
       onError={(error) => {
-        console.error("An error occurred:", error);
-      }}
-      onLogout={() => {
-        console.log("User logged out");
+        console.error("Authentication error:", error);
       }}
     >
-      <div>
-        <h1>Welcome to My App</h1>
-        <ShogunButton />
+      <div className="app">
+        <header>
+          <h1>Welcome to My Awesome App</h1>
+          <ShogunButton />
+        </header>
+        <main>{/* Your app content */}</main>
       </div>
     </ShogunButtonProvider>
   );
@@ -84,7 +72,44 @@ function App() {
 export default App;
 ```
 
-## API Reference
+## 🔧 Advanced Configuration
+
+### Custom Authentication Options
+
+```tsx
+const { core, options } = shogunConnector({
+  appName: "My App",
+
+  // Toggle authentication methods in the UI
+  showMetamask: true,
+  showWebauthn: true,
+  showNostr: true,
+  showOauth: true,
+
+  // Network configuration
+  peers: [
+    "https://gun-manhattan.herokuapp.com/gun"
+  ],
+
+  // OAuth provider configuration (optional)
+  oauth: {
+    providers: {
+      google: {
+        clientId: "your-google-client-id",
+        redirectUri: "https://myapp.com/auth/callback"
+      }
+    }
+  },
+
+  // Gun Advanced Plugin configuration
+  enableGunDebug: true,
+  enableConnectionMonitoring: true,
+  defaultPageSize: 20,
+  connectionTimeout: 10000,
+});
+```
+
+## 🎯 API Reference
 
 ### ShogunButtonProvider
 
@@ -92,130 +117,366 @@ The provider component that supplies Shogun context to your application.
 
 #### Props
 
-| Name            | Type                                                                                          | Description                                    |
-| --------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------- |
-| sdk             | ShogunCore                                                                                    | Shogun SDK instance created by shogunConnector |
-| options         | ShogunConnectorOptions                                                                        | Configuration options                          |
-| onLoginSuccess  | (data: { userPub: string; username: string; password?: string; authMethod?: string }) => void | Callback fired on successful login             |
-| onSignupSuccess | (data: { userPub: string; username: string; password?: string; authMethod?: string }) => void | Callback fired on successful signup            |
-| onError         | (error: string) => void                                                                       | Callback fired when an error occurs            |
-| onLogout        | () => void                                                                                    | Callback fired when user logs out              |
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| `core` | `ShogunCore` | Shogun SDK instance created by `shogunConnector` | ✅ |
+| `options` | `ShogunConnectorOptions` | Configuration options | ✅ |
+| `onLoginSuccess` | `(data: AuthData) => void` | Callback fired on successful login | ❌ |
+| `onSignupSuccess` | `(data: AuthData) => void` | Callback fired on successful signup | ❌ |
+| `onError` | `(error: string) => void` | Callback fired when an error occurs | ❌ |
+
+#### AuthData Interface
+
+```typescript
+interface AuthData {
+  userPub: string;           // User's public key
+  username: string;          // Display name
+  password?: string;         // Password (if applicable)
+  authMethod?: "password" | "web3" | "webauthn" | "nostr" | "oauth" | "pair";
+}
+```
 
 ### ShogunButton
 
-The main button component for triggering Shogun authentication. The component provides a complete authentication UI with modal dialogs for login and signup.
+The main button component that provides a complete authentication UI with modal dialogs for login, signup, and account management.
+
+**Features:**
+- Multi-method authentication selection
+- Password-based login/signup with recovery
+- Gun pair export/import for account backup
+- Responsive modal design
+- Error handling and user feedback
 
 ### useShogun Hook
 
-A hook to access Shogun authentication state and functions.
+A comprehensive hook to access Shogun authentication state and functions.
 
 ```tsx
 import React, { useEffect } from "react";
 import { useShogun } from "shogun-button-react";
 
-function Profile() {
+function UserProfile() {
   const {
+    // Authentication state
     isLoggedIn,
     userPub,
     username,
+
+    // Authentication methods
     login,
-    signup,
+    signUp,
     logout,
+
+    // Plugin management
     hasPlugin,
     getPlugin,
+
+    // Account management
     exportGunPair,
     importGunPair,
+
+    // Data operations
     observe,
+    put,
+    get,
+    remove,
+
+    // Advanced Gun hooks
+    useGunState,
+    useGunCollection,
+    useGunConnection,
+    useGunDebug,
+    useGunRealtime,
   } = useShogun();
 
-  const handleLogin = async () => {
-    // Login with username/password
-    await login("password", "username", "password");
-
-    // Or login with MetaMask
-    await login("web3");
-
-    // Or login with WebAuthn
-    await login("webauthn", "username");
-
-    // Or login with Nostr
-    await login("nostr");
-
-    // Or login with OAuth
-    await login("oauth", "google");
-
-    // Or login with Gun pair (for account recovery)
-    const pairData = {
-      /* Gun pair object */
-    };
-    await login("pair", pairData);
+  // Example: Login with different methods
+  const handlePasswordLogin = async () => {
+    try {
+      const result = await login("password", "username", "password");
+      if (result.success) {
+        console.log("Password login successful!");
+      }
+    } catch (error) {
+      console.error("Login failed:", error);
+    }
   };
 
-  const handleSignUp = async () => {
-    // Sign up with username/password
-    await signup("password", "newusername", "newpassword");
+  const handleMetaMaskLogin = async () => {
+    try {
+      const result = await login("web3");
+      if (result.success) {
+        console.log("MetaMask login successful!");
+      }
+    } catch (error) {
+      console.error("MetaMask login failed:", error);
+    }
+  };
 
-    // Or sign up with other methods (similar to login)
-    await signup("web3");
-    await signup("webauthn", "newusername");
+  const handleWebAuthnLogin = async () => {
+    try {
+      const result = await login("webauthn", "username");
+      if (result.success) {
+        console.log("WebAuthn login successful!");
+      }
+    } catch (error) {
+      console.error("WebAuthn login failed:", error);
+    }
   };
 
-  const handleExportPair = async () => {
+  // Example: Account backup and recovery
+  const handleExportAccount = async () => {
     try {
-      const pairData = await exportGunPair("optional-encryption-password");
-      console.log("Exported pair:", pairData);
-      // Save this data securely for account recovery
+      const pairData = await exportGunPair("my-secure-password");
+      console.log("Account exported successfully!");
+      
+      // Save to file or copy to clipboard
+      if (navigator.clipboard) {
+        await navigator.clipboard.writeText(pairData);
+        alert("Account data copied to clipboard!");
+      }
     } catch (error) {
       console.error("Export failed:", error);
     }
   };
 
-  const handleImportPair = async () => {
+  const handleImportAccount = async (pairData: string, password?: string) => {
     try {
-      const success = await importGunPair(savedPairData, "optional-password");
+      const success = await importGunPair(pairData, password);
       if (success) {
-        console.log("Pair imported successfully");
+        console.log("Account imported successfully!");
       }
     } catch (error) {
       console.error("Import failed:", error);
     }
   };
 
-  // Observe reactive data changes
+  // Example: Real-time data observation
   useEffect(() => {
     if (isLoggedIn) {
-      const subscription = observe<any>("user/profile").subscribe((data) => {
-        console.log("Profile data updated:", data);
+      const subscription = observe<any>('user/profile').subscribe(data => {
+        console.log('Profile updated:', data);
       });
-
+      
       return () => subscription.unsubscribe();
     }
   }, [isLoggedIn, observe]);
 
-  return isLoggedIn ? (
-    <div>
+  if (!isLoggedIn) {
+    return <div>Please log in to view your profile</div>;
+  }
+
+  return (
+    <div className="user-profile">
       <h2>Welcome, {username}!</h2>
-      <p>User Public Key: {userPub}</p>
-      <button onClick={logout}>Logout</button>
-      <button onClick={handleExportPair}>Export Account</button>
+      <div className="profile-info">
+        <p><strong>Public Key:</strong> {userPub}</p>
+        <p><strong>Authentication Method:</strong> {authMethod}</p>
+      </div>
+      
+      <div className="actions">
+        <button onClick={handleExportAccount}>Export Account</button>
+        <button onClick={logout}>Logout</button>
+      </div>
+    </div>
+  );
+}
+```
+
+## 🔌 Advanced Gun Plugin Usage
+
+### Using Gun State Hooks
+
+```tsx
+function UserSettings() {
+  const { useGunState, useGunCollection } = useShogun();
+  
+  // Single value state
+  const profile = useGunState('user/profile', {
+    name: '',
+    email: '',
+    preferences: {}
+  });
+  
+  // Collection management
+  const posts = useGunCollection('user/posts', {
+    pageSize: 10,
+    sortBy: 'createdAt',
+    sortOrder: 'desc',
+    filter: (post) => post.isPublished
+  });
+
+  const updateProfile = async () => {
+    await profile.update({
+      name: 'New Name',
+      preferences: { theme: 'dark' }
+    });
+  };
+
+  const addPost = async () => {
+    await posts.addItem({
+      title: 'New Post',
+      content: 'Post content...',
+      createdAt: Date.now(),
+      isPublished: true
+    });
+  };
+
+  return (
+    <div>
+      <h3>Profile Settings</h3>
+      {profile.isLoading ? (
+        <p>Loading...</p>
+      ) : profile.error ? (
+        <p>Error: {profile.error}</p>
+      ) : (
+        <div>
+          <input
+            value={profile.data?.name || ''}
+            onChange={(e) => profile.update({ name: e.target.value })}
+            placeholder="Name"
+          />
+          <button onClick={updateProfile}>Save Changes</button>
+        </div>
+      )}
+
+      <h3>Your Posts ({posts.items.length})</h3>
+      {posts.isLoading ? (
+        <p>Loading posts...</p>
+      ) : (
+        <div>
+          {posts.items.map((post, index) => (
+            <div key={index}>
+              <h4>{post.title}</h4>
+              <p>{post.content}</p>
+            </div>
+          ))}
+          
+          <div className="pagination">
+            {posts.hasPrevPage && (
+              <button onClick={posts.prevPage}>Previous</button>
+            )}
+            <span>Page {posts.currentPage + 1} of {posts.totalPages}</span>
+            {posts.hasNextPage && (
+              <button onClick={posts.nextPage}>Next</button>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Connection Monitoring
+
+```tsx
+function ConnectionStatus() {
+  const { useGunConnection, useGunDebug } = useShogun();
+  
+  // Monitor connection status
+  const connection = useGunConnection('user/data');
+  
+  // Enable debug logging
+  useGunDebug('user/data', true);
+
+  return (
+    <div className="connection-status">
+      <div className={`status-indicator ${connection.isConnected ? 'connected' : 'disconnected'}`}>
+        {connection.isConnected ? '🟢 Connected' : '🔴 Disconnected'}
+      </div>
+      
+      {connection.lastSeen && (
+        <p>Last seen: {connection.lastSeen.toLocaleTimeString()}</p>
+      )}
+      
+      {connection.error && (
+        <p className="error">Error: {connection.error}</p>
+      )}
     </div>
-  ) : (
-    <div>Please login to continue</div>
   );
 }
 ```
 
-## Configuration Options
+## 🎨 Customization
+
+### CSS Variables
+
+Customize the appearance using CSS variables:
+
+```css
+:root {
+  /* Primary colors */
+  --shogun-primary: #3b82f6;
+  --shogun-primary-hover: #2563eb;
+  
+  /* Background colors */
+  --shogun-bg: #ffffff;
+  --shogun-bg-secondary: #f3f4f6;
+  
+  /* Text colors */
+  --shogun-text: #1f2937;
+  --shogun-text-secondary: #6b7280;
+  
+  /* Border and shadow */
+  --shogun-border: #e5e7eb;
+  --shogun-border-radius: 12px;
+  --shogun-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+  
+  /* Transitions */
+  --shogun-transition: all 0.2s ease;
+}
+
+/* Dark mode overrides */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --shogun-bg: #1f2937;
+    --shogun-bg-secondary: #374151;
+    --shogun-text: #f3f4f6;
+    --shogun-text-secondary: #9ca3af;
+    --shogun-border: #4b5563;
+  }
+}
+```
+
+### Custom Styling
+
+```css
+/* Custom button styles */
+.shogun-connect-button {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  border-radius: 25px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 1px;
+}
+
+/* Custom modal styles */
+.shogun-modal {
+  border-radius: 20px;
+  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.1);
+}
+
+/* Custom form styles */
+.shogun-form-group input {
+  border-radius: 10px;
+  border: 2px solid transparent;
+  transition: border-color 0.3s ease;
+}
+
+.shogun-form-group input:focus {
+  border-color: var(--shogun-primary);
+  box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
+}
+```
+
+## 🔧 Configuration Options
 
-The `shogunConnector` accepts the following options:
+### Complete Configuration Interface
 
 ```typescript
 interface ShogunConnectorOptions {
   // App information
   appName: string;
-  appDescription?: string;
-  appUrl?: string;
-  appIcon?: string;
 
   // Feature toggles
   showMetamask?: boolean;
@@ -225,165 +486,102 @@ interface ShogunConnectorOptions {
   darkMode?: boolean;
 
   // Network configuration
-  websocketSecure?: boolean;
-  providerUrl?: string | null;
   peers?: string[];
   authToken?: string;
   gunInstance?: IGunInstance<any>;
 
-  // Advanced options
+  // Timeouts and provider configs
   timeouts?: {
     login?: number;
     signup?: number;
     operation?: number;
   };
   oauth?: {
-    providers: Record<
-      string,
-      {
-        clientId: string;
-        clientSecret?: string;
-        redirectUri?: string;
-      }
-    >;
+    providers: Record<string, {
+      clientId: string;
+      redirectUri?: string;
+      clientSecret?: string;
+    }>;
   };
+
+  // Gun Advanced Plugin configuration
+  enableGunDebug?: boolean;
+  enableConnectionMonitoring?: boolean;
+  defaultPageSize?: number;
+  connectionTimeout?: number;
+  debounceInterval?: number;
 }
 ```
 
-The `shogunConnector` returns an object with the following properties:
+### Connector Result
 
 ```typescript
 interface ShogunConnectorResult {
-  sdk: ShogunCore;
+  core: ShogunCore;
   options: ShogunConnectorOptions;
+  setProvider: (provider: any) => boolean;
+  getCurrentProviderUrl: () => string | null;
   registerPlugin: (plugin: any) => boolean;
   hasPlugin: (name: string) => boolean;
+  gunPlugin: GunAdvancedPlugin;
 }
 ```
 
-## Authentication Methods
-
-### Password Authentication
-
-```tsx
-// Login
-await login("password", "username", "password");
-
-// Sign up
-await signup("password", "username", "password");
-```
-
-### Web3 Authentication (MetaMask)
-
-```tsx
-// Login with MetaMask
-await login("web3");
-
-// Sign up with MetaMask
-await signup("web3");
-```
-
-### WebAuthn Authentication
-
-```tsx
-// Login with WebAuthn
-await login("webauthn", "username");
-
-// Sign up with WebAuthn
-await signup("webauthn", "username");
-```
-
-### Nostr Authentication
-
-```tsx
-// Login with Nostr
-await login("nostr");
-
-// Sign up with Nostr
-await signup("nostr");
-```
-
-### OAuth Authentication
+## 🌐 Browser Support
 
-```tsx
-// Login with OAuth provider
-await login("oauth", "google");
+- **Chrome** ≥ 60
+- **Firefox** ≥ 60
+- **Safari** ≥ 12
+- **Edge** ≥ 79
 
-// Sign up with OAuth provider
-await signup("oauth", "google");
-```
+## 📱 Mobile Support
 
-### Account Recovery (Gun Pair)
+The library is fully responsive and works seamlessly on mobile devices. All authentication methods are optimized for touch interfaces.
 
-```tsx
-// Login with exported pair
-await login("pair", pairData);
+## 🔒 Security Features
 
-// Sign up with pair
-await signup("pair", pairData);
-```
+- **Encrypted Storage**: Gun pairs can be encrypted with passwords
+- **Secure Authentication**: Multiple secure authentication methods
+- **Session Management**: Automatic session handling and cleanup
+- **Error Handling**: Comprehensive error handling and user feedback
 
-## Plugin Management
+## 🚀 Performance
 
-```tsx
-const { hasPlugin, getPlugin } = useShogun();
+- **Lazy Loading**: Components load only when needed
+- **Optimized Rendering**: Efficient React rendering with proper memoization
+- **Connection Pooling**: Smart connection management for optimal performance
+- **Debounced Updates**: Prevents excessive re-renders during rapid data changes
 
-// Check if a plugin is available
-if (hasPlugin("web3")) {
-  const web3Plugin = getPlugin("web3");
-  // Use the plugin
-}
+## 🤝 Contributing
 
-// Available plugins: "web3", "webauthn", "nostr", "oauth"
-```
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
-## Styling
+### Development Setup
 
-The component comes with default styling that you can override using CSS variables:
+```bash
+# Clone the repository
+git clone https://github.com/shogun/shogun-button-react.git
 
-```css
-:root {
-  --shogun-button-primary: #5c6bc0;
-  --shogun-button-hover: #3f51b5;
-  --shogun-text-primary: #333333;
-  --shogun-background: #ffffff;
-  --shogun-border-radius: 8px;
-  --shogun-font-family:
-    -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-  --shogun-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
-  --shogun-transition: all 0.2s ease-in-out;
-}
-```
+# Install dependencies
+yarn install
 
-### Dark Mode
+# Start development server
+yarn dev
 
-Enable dark mode by setting the `darkMode` option to `true`:
+# Build the library
+yarn build
 
-```tsx
-const { sdk, options } = shogunConnector({
-  appName: "My App",
-  darkMode: true, // Enable dark mode
-});
+# Run tests
+yarn test
 ```
 
-## Browser Support
-
-- Chrome ≥ 60
-- Firefox ≥ 60
-- Safari ≥ 12
-- Edge ≥ 79
-
-## Dependencies
-
-- React ≥ 18.0.0
-- shogun-core ≥ 1.5.19
-- ethers ≥ 6.13.5
-- rxjs ≥ 7.8.1
+## 📄 License
 
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+MIT © [Shogun](https://github.com/shogun)
 
-## License
+## 🆘 Support
 
-MIT © [Shogun](https://github.com/shogun)
+- **Documentation**: [Full API Reference](https://docs.shogun.dev)
+- **Issues**: [GitHub Issues](https://github.com/shogun/shogun-button-react/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/shogun/shogun-button-react/discussions)
+- **Discord**: [Join our community](https://discord.gg/shogun)